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 status : 'a status -> 'a task
The task that immediately finishes with provided status
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 on_server_activity : server -> (unit -> unit) -> unit
Idle server callback
val on_server_start : server -> (unit -> unit) -> unit
On-start server callback
val on_server_stop : server -> (unit -> unit) -> unit
On-stop server callback
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.