Concurrency library
Type of fiber. A fiber represent a suspended computation. Note that using the same fiber twice will execute it twice, which is probably not what you want. To share the result of a fiber, use an Ivar.t.
val return : 'a -> 'a tCreate a fiber that has already terminated.
Converts a thunk to a fiber, making sure the thunk runs in the context of the fiber (rather than applied in the current context).
Equivalent to (>>=) (return ()), but more explicit.
val never : 'a tFiber that never completes.
module O : sig ... endmodule Future : sig ... endfork f creates a sub-fiber and return a Future.t to wait its result.
nfork l is similar to fork but creates n sub-fibers.
nfork_map l ~f is the same as nfork (List.map l ~f:(fun x () -> f x)) but more efficient.
The following combinators are helpers to combine the result of several fibers into one. Note that they do not introduce parallelism.
The following functions combine forking 2 or more fibers followed by joining the results. For every function, we give an equivalent implementation using the more basic functions as documentation. Note however that these functions are implemented as primitives and so are more efficient that the suggested implementation.
For two fibers and wait for their results:
let fork_and_join f g =
fork f >>= fun a ->
fork g >>= fun b -> both (Future.wait a) (Future.wait b)Same but assume the first fiber returns unit:
let fork_and_join_unit f g =
fork f >>= fun a ->
fork g >>= fun b -> Future.wait a >>> Future.wait bval fork_and_race :
(unit -> 'a t) ->
(unit -> 'b t) ->
('a, 'b) Stdune.Either.t tMap a list in parallel:
let parallel_map l ~f =
nfork_map l ~f >>= fun futures -> all (List.map futures ~f:Future.wait)Iter over a list in parallel:
let parallel_iter l ~f =
nfork_map l ~f >>= fun futures ->
all_unit (List.map futures ~f:Future.wait)module Var : sig ... endVariables local to a fiber
val with_error_handler :
(unit -> 'a t) ->
on_error:(Stdune.Exn_with_backtrace.t -> unit) ->
'a twith_error_handler f ~on_error calls on_error for every exception raised during the execution of f. This include exceptions raised when calling f () or during the execution of fibers after f () has returned. Exceptions raised by on_error are passed on to the parent error handler.
It is guaranteed that after the fiber has returned a value, on_error will never be called.
val fold_errors :
(unit -> 'a t) ->
init:'b ->
on_error:(Stdune.Exn_with_backtrace.t -> 'b -> 'b) ->
('a, 'b) Stdune.Result.t tfold_errors f ~init ~on_error calls on_error for every exception raised during the execution of f. This include exceptions raised when calling f () or during the execution of fibers after f () has returned.
Exceptions raised by on_error are passed on to the parent error handler.
val collect_errors :
(unit -> 'a t) ->
('a, Stdune.Exn_with_backtrace.t list) Stdune.Result.t tcollect_errors f is: fold_errors f ~init:[] ~on_error:(fun e l -> e :: l)
finalize f ~finally runs finally after f () has terminated, whether it fails or succeeds.
module Ivar : sig ... endWrite once variables
module Mutex : sig ... endval run : 'a t -> 'a optionrun t runs a fiber. If the fiber doesn't complete immediately, run t returns None.
module Mvar : sig ... endMailbox variables