module Shell_uq

: sig

Run shell commands within Unixqueues

This module is not thread-safe. See the module Shell_sys for more information.

Signal handlers: It is important to have a number of signal handlers installed for proper function of the engines. It is recommended to call the pair of functions Shell_sys.configure_job_handlers and Shell_sys.install_job_handlers for this purpose. This is not done automatically.

Note that this has a global side effect on the whole process, because there is only one set of signal handlers.


class type ['t] job_handler_engine_type =
inherit ['t] Uq_engines.engine
method job : Shell_sys.job

Returns the called job

method job_instance : Shell_sys.job_instance

Returns the job instance

This type of engine also returns the job and the job_instance.

class call_engine : ?ignore_error_code:bool option -> ?mode:Shell_sys.group_mode option -> ?stdin:Shell.producer option -> ?stdout:Shell.consumer option -> ?stderr:Shell.consumer option -> Shell_sys.command list -> Unixqueue.event_system -> [Shell_sys.job_status] job_handler_engine_type

This engine corresponds to Shell.call. The command list is executed until the job is done. In this case, the status of the engine changes to `Done or `Error. If not ignore_error_code, failed jobs are reported by the error status `Error Subprocess_failure. If ignore_error_code, failed jobs are ignored, and result in the status `Done (however, jobs terminated by signals are still reported as errors).

For the other arguments see Shell.call.

When the engine goes to `Error or `Aborted, the job is terminated ( Shell_sys.abandon_job ).


All examples presented for the [root:Shell] module can be easily rewritten for Shell_uq. For example, to call "ls" and collect the result in a buffer, use this piece of code:

   let ues = Unixqueue.create_unix_event_system();;
   let b = Buffer.create 10;;
   let e = new call_engine ~stdout:(Shell.to_buffer b) [ Shell.command "ls" ];;
   Unixqueue.run ues;;
   let r = Buffer.contents b;;

This means, one simply creates a call_engine instead of invoking Shell.call, and then runs the queue. Note that you must look at e#state to find out whether the engine e produced an error, no exception is raised in this case.

It is allowed (and somehow the purpose of this module) to create several job engines, and let them run in parallel.