Module Task


module Task: sig .. end
High Level Interface to Command.
Since Carbon-20101201


Task


type 'a task 

type 'a status =
| Canceled
| Result of 'a
| Failed of exn

type 'a running =
| Running of (unit -> unit)
| Finished of 'a status
val start : 'a task -> unit
val cancel : 'a task -> unit
val wait : 'a task -> 'a status
Blocks until termination.
val ping : 'a task -> 'a running

Monadic Constructors


val nop : unit task
The task that immediately returns unit
val return : 'a -> 'a task
The task that immediately returns a result
val raised : exn -> 'a task
The task that immediately fails with an exception
val canceled : unit -> 'a task
The task that is immediately canceled
val failed : ('a, Format.formatter, unit, 'b task) Pervasives.format4 -> 'a
The task that immediately fails by raising a Failure exception. Typically: [let exit d : 'a task = failed "exit status %d" k]
val call : ('a -> 'b) -> 'a -> 'b task
The task that, when started, invokes a function and immediately returns the result.
val bind : 'a task -> ('a status -> 'b task) -> 'b task
bind t k first runs t. Then, when t exit with status s, it starts task k s.

Remark: If t was cancelled, k s is still evaluated, but immediately canceled as well. This allows finally-like behaviors to be implemented. To evaluate k r only when t terminates normally, make use of the sequence operator.

val sequence : 'a task -> ('a -> 'b task) -> 'b task
sequence t k first runs t. If t terminates with Result r, then task k r is started. Otherwise, failure or cancelation of t is returned.
val todo : (unit -> 'a task) -> 'a task
todo f is a useful short-cut for sequence nop t
val finally : 'a task -> ('a status -> unit) -> 'a task
finally t cb runs task t and always calls cb s when t exits with status s. Then s is returned. If the callback cb raises an exception, the returned status is emitted.
val callback : 'a task -> ('a status -> unit) -> unit task
Same as finally but the status of the task is discarded.
val (>>>) : 'a task -> ('a status -> 'b task) -> 'b task
bind infix.
val (>>=) : 'a task -> ('a -> 'b task) -> 'b task
sequence infix.
val (>>?) : 'a task -> ('a status -> unit) -> 'a task
finally infix.
val (>>!) : 'a task -> ('a status -> unit) -> unit task
callback infix.

Synchroneous Command


type mutex 
val mutex : unit -> mutex
val sync : mutex -> (unit -> 'a task) -> 'a task
Schedules a task such that only one can run simultaneously for a given mutex.

System Command


val command : ?timeout:int ->
?stdout:Buffer.t ->
?stderr:Buffer.t -> string -> string array -> int task
Immediately launch a system-process. Default timeout is 0, which means no-timeout at all. Standard outputs are discarded unless optional buffers are provided. To make the task start later, simply use todo (command ...).

Task Server


type server 
val server : ?stages:int -> ?procs:int -> unit -> server
Creates a server of commands.
stages : number of queues in the server. Stage 0 tasks are issued first. Default is 1.
procs : maximum number of running tasks. Default is 4.
val spawn : server -> ?stage:int -> unit task -> unit
Schedules a task on the server. The task is not immediately started.
val launch : server -> unit
Starts the server if not running yet
val cancel_all : server -> unit
Cancel all scheduled tasks
val set_procs : server -> int -> unit
Adjusts the maximum number of running process.
val set_callback : server -> (unit -> unit) -> unit
The callback is called at each idle time
val load : server -> int
Number of scheduled process

GUI Configuration


val on_idle : ((unit -> bool) -> unit) Pervasives.ref
Typically modified by GUI. !on_idle f should repeatedly calls f until it returns false. Default implementation rely on Unix.sleep 1 and Db.progress. See also Gtk_helper module implementation.