Module `Fiber`Source

Concurrency library

This module implements "structured concurrency".

alert unstable The API of this library is not stable and may change without notice.

Generals

Sourcetype 'a t

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.

Sourcetype 'a fiber := 'a t

Sourceval return : 'a -> 'a t

Create a fiber that has already terminated.

Sourceval of_thunk : (unit -> 'a t) -> 'a t

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.

Sourceval never : 'a t

Fiber that never completes.

Sourcemodule O : sig ... end

Sourceval map : 'a t -> f:('a -> 'b) -> 'b t

Sourceval bind : 'a t -> f:('a -> 'b t) -> 'b t

Joining

The following combinators are helpers to combine the result of several fibers into one. Note that they do not introduce parallelism.

Sourceval both : 'a t -> 'b t -> ('a * 'b) t

Sourceval all : 'a t list -> 'a list t

Execute a list of fibers in sequence. We use the short name to conform with the Applicative interface.

Sourceval sequential_map : 'a list -> f:('a -> 'b t) -> 'b list t

Sourceval sequential_iter : 'a list -> f:('a -> unit t) -> unit t

Forking + joining

The following functions combine forking 2 or more fibers followed by joining the results. The execution of the various fibers might be interleaved, however once the combining fiber has terminated, it is guaranteed that there are no fibers lingering around.

Sourceval fork_and_join : (unit -> 'a t) -> (unit -> 'b t) -> ('a * 'b) t

Start two fibers and wait for their result. Note that this function combines both successes and errors: if one of the computations fails, we let the other one run to completion, to give it a chance to raise its errors too. All other parallel execution combinators have the same error semantics.

Sourceval fork_and_join_unit : (unit -> unit t) -> (unit -> 'a t) -> 'a t

Same but assume the first fiber returns unit.

Sourceval parallel_map : 'a list -> f:('a -> 'b t) -> 'b list t

Map a list in parallel.

Sourceval all_concurrently : 'a t list -> 'a list t

Like all but executes the fibers concurrently.

Sourceval all_concurrently_unit : unit t list -> unit t

Like all_concurrently but is specialized for unit fibers. The advantage being that it doesn't allocate a return list.

Sourceval parallel_iter : 'a list -> f:('a -> unit t) -> unit t

Iter over a list in parallel.

Source

val parallel_iter_set : 
  (module Stdune.Set.S with type elt = 'a and type t = 's) ->
  's ->
  f:('a -> unit t) ->
  unit t

Sourceval sequential_iter_seq : 'a Stdune.Seq.t -> f:('a -> unit t) -> unit t

Sourcemodule Make_map_traversals (Map : Stdune.Map.S) : sig ... end

Provide efficient parallel iter/map functions for maps.

Local storage

Sourcemodule Var : sig ... end

Variables local to a fiber

Error handling

Source

val with_error_handler : 
  (unit -> 'a t) ->
  on_error:(Stdune.Exn_with_backtrace.t -> Stdune.Nothing.t t) ->
  'a t

with_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.

Source

val map_reduce_errors : 
  (module Stdune.Monoid with type t = 'a) ->
  on_error:(Stdune.Exn_with_backtrace.t -> 'a t) ->
  (unit -> 'b t) ->
  ('b, 'a) Stdune.result t

Source

val collect_errors : 
  (unit -> 'a t) ->
  ('a, Stdune.Exn_with_backtrace.t list) Stdune.Result.t t

collect_errors f is: fold_errors f ~init:[] ~on_error:(fun e l -> e :: l)

Sourceval finalize : (unit -> 'a t) -> finally:(unit -> unit t) -> 'a t

finalize f ~finally runs finally after f () has terminated, whether it fails or succeeds.

Sourceval reraise_all : Stdune.Exn_with_backtrace.t list -> 'a t

reraise_all exns re-raises all exns to the current error handler

Synchronization

Sourcemodule Ivar : sig ... end

Write once variables

Sourcemodule Mvar : sig ... end

Mailbox variables

Sourcemodule Svar : sig ... end

State variables

Sourcemodule Mutex : sig ... end

Sourcemodule Throttle : sig ... end

Limit the number of jobs

Sourceval repeat_while : f:('a -> 'a option t) -> init:'a -> unit t

Sourcemodule Stream : sig ... end

Destructive streams that can be composed to pipelines.

Sourcemodule Pool : sig ... end

Running fibers

Sourcetype fill =

| Fill : 'a Ivar.t * 'a -> fill

Sourceval run : 'a t -> iter:(unit -> fill Stdune.Nonempty_list.t) -> 'a

run t ~iter runs a fiber until it terminates. iter is used to implement the scheduler, it should block waiting for an event and return at least one ivar to fill.

Sourcemodule Scheduler : sig ... end

Advanced fiber execution

Sourcemodule Cancel : sig ... end

Sourcemodule Expert : sig ... end

This module offers no safety protections. It is only needed for maximizing performance in certain situations

package fiber

Module FiberSource

Generals

Joining

Forking + joining

Local storage

Error handling

Synchronization

Running fibers

Module `Fiber`Source