Module Procord_process

module Procord_process: sig .. end

Delegating tasks to other processes.

type 'a process

The type of processes.

Delegating Tasks

val delegate : ('a, 'b) Procord_task.delegated_task -> 'a -> 'b process

Delegate according to command-line options parsed by Procord_worker.run.

The task starts to run in the background immediately.

If command-line argument --procord-hostname is empty, delegate using Unix.create_process, to the executable Sys.executable_name. Else, delegate using a socket connection to a server worker (started with --procord-server) at the address specified by --procord-hostname, port --procord-port.

Call Procord_worker.run at the beginning at your program if you plan to use this function. Otherwise, use one of the alternatives below.

val delegate_task_create_process : ?stderr:Unix.file_descr ->
       string ->
       string array ->
       ('a, 'b) Procord_task.delegated_task -> 'a -> 'b process

Delegate a task, running it in another process on the current machine. The process is created using Unix.create_process.

The task starts to run in the background immediately.

Usage: delegate_task_create_process ?stderr program arguments task input

The program is the executable file name. It can be the main program file name itself (Sys.executable_name), if it has a way to distinguish whether it is a worker, for instance from command-line arguments.

stderr : If specified, the created process will have its standard error redirected to stderr. If unspecified, everything the created process writes on its standard error will be ignored. Example: Unix.stderr

val delegate_task_socket : string ->
       int ->
       ('a, 'b) Procord_task.delegated_task -> 'a -> 'b process

Delegate a task, running it in another process on a remote machine.

The socket is created immediately.

Usage: delegate_task_socket hostname port task input

The task will be delegated to a worker running on remote machine hostname, listening on port.

The hostname can be an IP address, an IPv6 address or a DNS address.

Running Processes

To run a process, either call run_process (which is blocking), or call update followed by process_status regularly. Wait using process_waiter between two updates.

type execution_error =

`\|`	`Worker_unknown_exception of string`	`(*`	A worker raised an exception which was not handled by `write_exception`. The `string` is obtained using `Printexc`.	`*)`
`\|`	`Worker_killed`	`(*`	You killed the worker yourself.	`*)`
`\|`	`Worker_disconnected of exn`	`(*`	An exception was raised while trying to connect to, send to, or receive from a worker; or the worker was killed, crashed or exited without returning any output; or there was an error while serializing an input value or deserializing an output value.	`*)`
`\|`	`No_worker_available of string`	`(*`	No worker is available to perform the required task, or the selected worker cannot perform the required task. The string is the task name.	`*)`

Execution error descriptions.

exception Execution_error of execution_error

An unexpected error occurred when delegating a task.

val error_message : execution_error -> string

Return a string explaining an error in English.

type 'a status =

`\|`	`Working`	`(*`	The task is not finished yet.	`*)`
`\|`	`Success of 'a`	`(*`	The task was performed successfully, `'a` is the result.	`*)`
`\|`	`Exception of exn`	`(*`	The task resulted in an exception that `write_exception` could handle.	`*)`
`\|`	`Error of execution_error`	`(*`	Failed to execute the task.	`*)`

Status of a task given to a worker.

val waiter : 'a process -> Procord_connection.waiter

Return a waiter which waits until something happens for a process.

val update : 'a process -> unit

Call this regularly to update the process_status.

val status : 'a process -> 'a status

Get the current status of a process.

val run : 'a process -> 'a

Wait (blocking) until a process terminates.

Return the process return value or, if it raised an exception, raise this exception.

May also raise Execution_error.

val kill : 'a process -> unit

Terminate a process immediately.