diff --git a/dev/moonpool/Moonpool/Blocking_queue/index.html b/dev/moonpool/Moonpool/Blocking_queue/index.html index 987b93ac..a8bdf072 100644 --- a/dev/moonpool/Moonpool/Blocking_queue/index.html +++ b/dev/moonpool/Moonpool/Blocking_queue/index.html @@ -14,4 +14,4 @@ one single critical section. *) Bb_queue.transfer work_queue local_q done - with Bb_queue.Closed -> ()
type 'a gen = unit -> 'a option
type 'a iter = ('a -> unit) -> unit
val to_iter : 'a t -> 'a iter

to_iter q returns an iterator over all items in the queue. This might not terminate if q is never closed.

val to_gen : 'a t -> 'a gen

to_gen q returns a generator from the queue.

val to_seq : 'a t -> 'a Stdlib.Seq.t

to_gen q returns a (transient) sequence from the queue.

+ with Bb_queue.Closed -> ()
type 'a gen = unit -> 'a option
type 'a iter = ('a -> unit) -> unit
val to_iter : 'a t -> 'a iter

to_iter q returns an iterator over all items in the queue. This might not terminate if q is never closed.

val to_gen : 'a t -> 'a gen

to_gen q returns a generator from the queue.

val to_seq : 'a t -> 'a Stdlib.Seq.t

to_gen q returns a (transient) sequence from the queue.

diff --git a/dev/moonpool/Moonpool/Bounded_queue/index.html b/dev/moonpool/Moonpool/Bounded_queue/index.html index 6c5969b3..8fc91ff4 100644 --- a/dev/moonpool/Moonpool/Bounded_queue/index.html +++ b/dev/moonpool/Moonpool/Bounded_queue/index.html @@ -1,2 +1,2 @@ -Bounded_queue (moonpool.Moonpool.Bounded_queue)

Module Moonpool.Bounded_queue

A blocking queue of finite size.

This queue, while still using locks underneath (like the regular blocking queue) should be enough for usage under reasonable contention.

The bounded size is helpful whenever some form of backpressure is desirable: if the queue is used to communicate between producer(s) and consumer(s), the consumer(s) can limit the rate at which producer(s) send new work down their way. Whenever the queue is full, means that producer(s) will have to wait before pushing new work.

type 'a t

A bounded queue.

val create : max_size:int -> unit -> 'a t
val close : _ t -> unit

close q closes q. No new elements can be pushed into q, and after all the elements still in q currently are pop'd, pop will also raise Closed.

exception Closed
val push : 'a t -> 'a -> unit

push q x pushes x at the end of the queue. If q is full, this will block until there is room for x.

val try_push : force_lock:bool -> 'a t -> 'a -> bool

try_push q x attempts to push x into q, but abandons if it cannot acquire q or if q is full.

  • parameter force_lock

    if true, use Mutex.lock (which can block under contention); if false, use Mutex.try_lock, which might return false even if there's room in the queue.

val pop : 'a t -> 'a

pop q pops the first element off q. It blocks if q is empty, until some element becomes available.

  • raises Closed

    if q is empty and closed.

val try_pop : force_lock:bool -> 'a t -> 'a option

try_pop ~force_lock q tries to pop the first element, or returns None if no element is available or if it failed to acquire q.

  • parameter force_lock

    if true, use Mutex.lock (which can block under contention); if false, use Mutex.try_lock, which might return None even in presence of an element if there's contention.

  • raises Closed

    if q is empty and closed.

val size : _ t -> int

Number of elements currently in q

val max_size : _ t -> int

Maximum size of the queue. See create.

val transfer : 'a t -> 'a Stdlib.Queue.t -> unit

transfer bq q2 transfers all elements currently available in bq into local queue q2, and clears bq, atomically. It blocks if bq is empty.

See Bb_queue.transfer for more details.

  • raises Closed

    if bq is empty and closed.

type 'a gen = unit -> 'a option
type 'a iter = ('a -> unit) -> unit
val to_iter : 'a t -> 'a iter

to_iter q returns an iterator over all items in the queue. This might not terminate if q is never closed.

val to_gen : 'a t -> 'a gen

to_gen q returns a generator from the queue.

val to_seq : 'a t -> 'a Stdlib.Seq.t

to_gen q returns a (transient) sequence from the queue.

+Bounded_queue (moonpool.Moonpool.Bounded_queue)

Module Moonpool.Bounded_queue

A blocking queue of finite size.

This queue, while still using locks underneath (like the regular blocking queue) should be enough for usage under reasonable contention.

The bounded size is helpful whenever some form of backpressure is desirable: if the queue is used to communicate between producer(s) and consumer(s), the consumer(s) can limit the rate at which producer(s) send new work down their way. Whenever the queue is full, means that producer(s) will have to wait before pushing new work.

type 'a t

A bounded queue.

val create : max_size:int -> unit -> 'a t
val close : _ t -> unit

close q closes q. No new elements can be pushed into q, and after all the elements still in q currently are pop'd, pop will also raise Closed.

exception Closed
val push : 'a t -> 'a -> unit

push q x pushes x at the end of the queue. If q is full, this will block until there is room for x.

val try_push : force_lock:bool -> 'a t -> 'a -> bool

try_push q x attempts to push x into q, but abandons if it cannot acquire q or if q is full.

  • parameter force_lock

    if true, use Mutex.lock (which can block under contention); if false, use Mutex.try_lock, which might return false even if there's room in the queue.

val pop : 'a t -> 'a

pop q pops the first element off q. It blocks if q is empty, until some element becomes available.

  • raises Closed

    if q is empty and closed.

val try_pop : force_lock:bool -> 'a t -> 'a option

try_pop ~force_lock q tries to pop the first element, or returns None if no element is available or if it failed to acquire q.

  • parameter force_lock

    if true, use Mutex.lock (which can block under contention); if false, use Mutex.try_lock, which might return None even in presence of an element if there's contention.

  • raises Closed

    if q is empty and closed.

val size : _ t -> int

Number of elements currently in q

val max_size : _ t -> int

Maximum size of the queue. See create.

val transfer : 'a t -> 'a Stdlib.Queue.t -> unit

transfer bq q2 transfers all elements currently available in bq into local queue q2, and clears bq, atomically. It blocks if bq is empty.

See Bb_queue.transfer for more details.

  • raises Closed

    if bq is empty and closed.

type 'a gen = unit -> 'a option
type 'a iter = ('a -> unit) -> unit
val to_iter : 'a t -> 'a iter

to_iter q returns an iterator over all items in the queue. This might not terminate if q is never closed.

val to_gen : 'a t -> 'a gen

to_gen q returns a generator from the queue.

val to_seq : 'a t -> 'a Stdlib.Seq.t

to_gen q returns a (transient) sequence from the queue.

diff --git a/dev/moonpool/Moonpool/Fut/index.html b/dev/moonpool/Moonpool/Fut/index.html index ca03e0c2..2a11d383 100644 --- a/dev/moonpool/Moonpool/Fut/index.html +++ b/dev/moonpool/Moonpool/Fut/index.html @@ -1,2 +1,2 @@ -Fut (moonpool.Moonpool.Fut)

Module Moonpool.Fut

Futures.

A future of type 'a t represents the result of a computation that will yield a value of type 'a.

Typically, the computation is running on a thread pool Runner.t and will proceed on some worker. Once set, a future cannot change. It either succeeds (storing a Ok x with x: 'a), or fail (storing a Error (exn, bt) with an exception and the corresponding backtrace).

Combinators such as map and join_array can be used to produce futures from other futures (in a monadic way). Some combinators take a on argument to specify a runner on which the intermediate computation takes place; for example map ~on:pool ~f fut maps the value in fut using function f, applicatively; the call to f happens on the runner pool (once fut resolves successfully with a value).

type 'a or_error = ('a, exn * Stdlib.Printexc.raw_backtrace) result
type 'a t

A future with a result of type 'a.

type 'a promise

A promise, which can be fulfilled exactly once to set the corresponding future

val make : unit -> 'a t * 'a promise

Make a new future with the associated promise

val on_result : 'a t -> ('a or_error -> unit) -> unit

on_result fut f registers f to be called in the future when fut is set ; or calls f immediately if fut is already set.

exception Already_fulfilled
val fulfill : 'a promise -> 'a or_error -> unit

Fullfill the promise, setting the future at the same time.

val fulfill_idempotent : 'a promise -> 'a or_error -> unit

Fullfill the promise, setting the future at the same time. Does nothing if the promise is already fulfilled.

val return : 'a -> 'a t

Already settled future, with a result

val fail : exn -> Stdlib.Printexc.raw_backtrace -> _ t

Already settled future, with a failure

val of_result : 'a or_error -> 'a t
val is_resolved : _ t -> bool

is_resolved fut is true iff fut is resolved.

val peek : 'a t -> 'a or_error option

peek fut returns Some r if fut is currently resolved with r, and None if fut is not resolved yet.

exception Not_ready
  • since 0.2
val get_or_fail : 'a t -> 'a or_error

get_or_fail fut obtains the result from fut if it's fulfilled (i.e. if peek fut returns Some res, get_or_fail fut returns res).

  • since 0.2
val get_or_fail_exn : 'a t -> 'a

get_or_fail_exn fut obtains the result from fut if it's fulfilled, like get_or_fail. If the result is an Error _, the exception inside is re-raised.

  • since 0.2
val is_done : _ t -> bool

Is the future resolved? This is the same as peek fut |> Option.is_some.

  • since 0.2

Combinators

val spawn : on:Runner.t -> (unit -> 'a) -> 'a t

spaw ~on f runs f() on the given runner on, and return a future that will hold its result.

val reify_error : 'a t -> 'a or_error t

reify_error fut turns a failing future into a non-failing one that contain Error (exn, bt). A non-failing future returning x is turned into Ok x

  • since NEXT_RELEASE
val map : ?on:Runner.t -> f:('a -> 'b) -> 'a t -> 'b t

map ?on ~f fut returns a new future fut2 that resolves with f x if fut resolved with x; and fails with e if fut fails with e or f x raises e.

  • parameter on

    if provided, f runs on the given runner

val bind : ?on:Runner.t -> f:('a -> 'b t) -> 'a t -> 'b t

bind ?on ~f fut returns a new future fut2 that resolves like the future f x if fut resolved with x; and fails with e if fut fails with e or f x raises e.

  • parameter on

    if provided, f runs on the given runner

val bind_reify_error : ?on:Runner.t -> f:('a or_error -> 'b t) -> 'a t -> 'b t

bind_reify_error ?on ~f fut returns a new future fut2 that resolves like the future f (Ok x) if fut resolved with x; and resolves like the future f (Error (exn, bt)) if fut fails with exn and backtrace bt.

  • parameter on

    if provided, f runs on the given runner

  • since NEXT_RELEASE
val join : ?on:Runner.t -> 'a t t -> 'a t

join fut is fut >>= Fun.id. It joins the inner layer of the future.

  • since 0.2
val both : 'a t -> 'b t -> ('a * 'b) t

both a b succeeds with x, y if a succeeds with x and b succeeds with y, or fails if any of them fails.

val choose : 'a t -> 'b t -> ('a, 'b) Either.t t

choose a b succeeds Left x or Right y if a succeeds with x or b succeeds with y, or fails if both of them fails. If they both succeed, it is not specified which result is used.

val choose_same : 'a t -> 'a t -> 'a t

choose_same a b succeeds with the value of one of a or b if they succeed, or fails if both fail. If they both succeed, it is not specified which result is used.

val join_array : 'a t array -> 'a array t

Wait for all the futures in the array. Fails if any future fails.

val join_list : 'a t list -> 'a list t

Wait for all the futures in the list. Fails if any future fails.

val wait_array : _ t array -> unit t

wait_array arr waits for all futures in arr to resolve. It discards the individual results of futures in arr. It fails if any future fails.

val wait_list : _ t list -> unit t

wait_list l waits for all futures in l to resolve. It discards the individual results of futures in l. It fails if any future fails.

val for_ : on:Runner.t -> int -> (int -> unit) -> unit t

for_ ~on n f runs f 0, f 1, …, f (n-1) on the runner, and returns a future that resolves when all the tasks have resolved, or fails as soon as one task has failed.

val for_array : on:Runner.t -> 'a array -> (int -> 'a -> unit) -> unit t

for_array ~on arr f runs f 0 arr.(0), …, f (n-1) arr.(n-1) in the runner (where n = Array.length arr), and returns a future that resolves when all the tasks are done, or fails if any of them fails.

  • since 0.2
val for_list : on:Runner.t -> 'a list -> ('a -> unit) -> unit t

for_list ~on l f is like for_array ~on (Array.of_list l) f.

  • since 0.2

Await

NOTE This is only available on OCaml 5.

val await : 'a t -> 'a

await fut suspends the current tasks until fut is fulfilled, then resumes the task on this same runner.

  • since 0.3

This must only be run from inside the runner itself. The runner must support Suspend_. NOTE: only on OCaml 5.x

Blocking

val wait_block : 'a t -> 'a or_error

wait_block fut blocks the current thread until fut is resolved, and returns its value.

NOTE: A word of warning: this will monopolize the calling thread until the future resolves. This can also easily cause deadlocks, if enough threads in a pool call wait_block on futures running on the same pool or a pool depending on it.

A good rule to avoid deadlocks is to run this from outside of any pool, or to have an acyclic order between pools where wait_block is only called from a pool on futures evaluated in a pool that comes lower in the hierarchy. If this rule is broken, it is possible for all threads in a pool to wait for futures that can only make progress on these same threads, hence the deadlock.

val wait_block_exn : 'a t -> 'a

Same as wait_block but re-raises the exception if the future failed.

module type INFIX = sig ... end

Operators that run on the same thread as the first future.

include INFIX
val (>|=) : 'a t -> ('a -> 'b) -> 'b t
val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
val let+ : 'a t -> ('a -> 'b) -> 'b t
val and+ : 'a t -> 'b t -> ('a * 'b) t
val let* : 'a t -> ('a -> 'b t) -> 'b t
val and* : 'a t -> 'b t -> ('a * 'b) t
module Infix (_ : sig ... end) : INFIX

Make infix combinators, with intermediate computations running on the given pool.

val infix : Runner.t -> (module INFIX)

infix runner makes a new infix module with intermediate computations running on the given runner..

  • since 0.2
+Fut (moonpool.Moonpool.Fut)

Module Moonpool.Fut

Futures.

A future of type 'a t represents the result of a computation that will yield a value of type 'a.

Typically, the computation is running on a thread pool Runner.t and will proceed on some worker. Once set, a future cannot change. It either succeeds (storing a Ok x with x: 'a), or fail (storing a Error (exn, bt) with an exception and the corresponding backtrace).

Combinators such as map and join_array can be used to produce futures from other futures (in a monadic way). Some combinators take a on argument to specify a runner on which the intermediate computation takes place; for example map ~on:pool ~f fut maps the value in fut using function f, applicatively; the call to f happens on the runner pool (once fut resolves successfully with a value).

type 'a or_error = ('a, exn * Stdlib.Printexc.raw_backtrace) result
type 'a t

A future with a result of type 'a.

type 'a promise

A promise, which can be fulfilled exactly once to set the corresponding future

val make : unit -> 'a t * 'a promise

Make a new future with the associated promise

val on_result : 'a t -> ('a or_error -> unit) -> unit

on_result fut f registers f to be called in the future when fut is set ; or calls f immediately if fut is already set.

exception Already_fulfilled
val fulfill : 'a promise -> 'a or_error -> unit

Fullfill the promise, setting the future at the same time.

val fulfill_idempotent : 'a promise -> 'a or_error -> unit

Fullfill the promise, setting the future at the same time. Does nothing if the promise is already fulfilled.

val return : 'a -> 'a t

Already settled future, with a result

val fail : exn -> Stdlib.Printexc.raw_backtrace -> _ t

Already settled future, with a failure

val of_result : 'a or_error -> 'a t
val is_resolved : _ t -> bool

is_resolved fut is true iff fut is resolved.

val peek : 'a t -> 'a or_error option

peek fut returns Some r if fut is currently resolved with r, and None if fut is not resolved yet.

exception Not_ready
  • since 0.2
val get_or_fail : 'a t -> 'a or_error

get_or_fail fut obtains the result from fut if it's fulfilled (i.e. if peek fut returns Some res, get_or_fail fut returns res).

  • since 0.2
val get_or_fail_exn : 'a t -> 'a

get_or_fail_exn fut obtains the result from fut if it's fulfilled, like get_or_fail. If the result is an Error _, the exception inside is re-raised.

  • since 0.2
val is_done : _ t -> bool

Is the future resolved? This is the same as peek fut |> Option.is_some.

  • since 0.2

Combinators

val spawn : on:Runner.t -> (unit -> 'a) -> 'a t

spaw ~on f runs f() on the given runner on, and return a future that will hold its result.

val reify_error : 'a t -> 'a or_error t

reify_error fut turns a failing future into a non-failing one that contain Error (exn, bt). A non-failing future returning x is turned into Ok x

  • since 0.4
val map : ?on:Runner.t -> f:('a -> 'b) -> 'a t -> 'b t

map ?on ~f fut returns a new future fut2 that resolves with f x if fut resolved with x; and fails with e if fut fails with e or f x raises e.

  • parameter on

    if provided, f runs on the given runner

val bind : ?on:Runner.t -> f:('a -> 'b t) -> 'a t -> 'b t

bind ?on ~f fut returns a new future fut2 that resolves like the future f x if fut resolved with x; and fails with e if fut fails with e or f x raises e.

  • parameter on

    if provided, f runs on the given runner

val bind_reify_error : ?on:Runner.t -> f:('a or_error -> 'b t) -> 'a t -> 'b t

bind_reify_error ?on ~f fut returns a new future fut2 that resolves like the future f (Ok x) if fut resolved with x; and resolves like the future f (Error (exn, bt)) if fut fails with exn and backtrace bt.

  • parameter on

    if provided, f runs on the given runner

  • since 0.4
val join : ?on:Runner.t -> 'a t t -> 'a t

join fut is fut >>= Fun.id. It joins the inner layer of the future.

  • since 0.2
val both : 'a t -> 'b t -> ('a * 'b) t

both a b succeeds with x, y if a succeeds with x and b succeeds with y, or fails if any of them fails.

val choose : 'a t -> 'b t -> ('a, 'b) Either.t t

choose a b succeeds Left x or Right y if a succeeds with x or b succeeds with y, or fails if both of them fails. If they both succeed, it is not specified which result is used.

val choose_same : 'a t -> 'a t -> 'a t

choose_same a b succeeds with the value of one of a or b if they succeed, or fails if both fail. If they both succeed, it is not specified which result is used.

val join_array : 'a t array -> 'a array t

Wait for all the futures in the array. Fails if any future fails.

val join_list : 'a t list -> 'a list t

Wait for all the futures in the list. Fails if any future fails.

val wait_array : _ t array -> unit t

wait_array arr waits for all futures in arr to resolve. It discards the individual results of futures in arr. It fails if any future fails.

val wait_list : _ t list -> unit t

wait_list l waits for all futures in l to resolve. It discards the individual results of futures in l. It fails if any future fails.

val for_ : on:Runner.t -> int -> (int -> unit) -> unit t

for_ ~on n f runs f 0, f 1, …, f (n-1) on the runner, and returns a future that resolves when all the tasks have resolved, or fails as soon as one task has failed.

val for_array : on:Runner.t -> 'a array -> (int -> 'a -> unit) -> unit t

for_array ~on arr f runs f 0 arr.(0), …, f (n-1) arr.(n-1) in the runner (where n = Array.length arr), and returns a future that resolves when all the tasks are done, or fails if any of them fails.

  • since 0.2
val for_list : on:Runner.t -> 'a list -> ('a -> unit) -> unit t

for_list ~on l f is like for_array ~on (Array.of_list l) f.

  • since 0.2

Await

NOTE This is only available on OCaml 5.

val await : 'a t -> 'a

await fut suspends the current tasks until fut is fulfilled, then resumes the task on this same runner.

  • since 0.3

This must only be run from inside the runner itself. The runner must support Suspend_. NOTE: only on OCaml 5.x

Blocking

val wait_block : 'a t -> 'a or_error

wait_block fut blocks the current thread until fut is resolved, and returns its value.

NOTE: A word of warning: this will monopolize the calling thread until the future resolves. This can also easily cause deadlocks, if enough threads in a pool call wait_block on futures running on the same pool or a pool depending on it.

A good rule to avoid deadlocks is to run this from outside of any pool, or to have an acyclic order between pools where wait_block is only called from a pool on futures evaluated in a pool that comes lower in the hierarchy. If this rule is broken, it is possible for all threads in a pool to wait for futures that can only make progress on these same threads, hence the deadlock.

val wait_block_exn : 'a t -> 'a

Same as wait_block but re-raises the exception if the future failed.

module type INFIX = sig ... end

Operators that run on the same thread as the first future.

include INFIX
val (>|=) : 'a t -> ('a -> 'b) -> 'b t
val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
val let+ : 'a t -> ('a -> 'b) -> 'b t
val and+ : 'a t -> 'b t -> ('a * 'b) t
val let* : 'a t -> ('a -> 'b t) -> 'b t
val and* : 'a t -> 'b t -> ('a * 'b) t
module Infix (_ : sig ... end) : INFIX

Make infix combinators, with intermediate computations running on the given pool.

val infix : Runner.t -> (module INFIX)

infix runner makes a new infix module with intermediate computations running on the given runner..

  • since 0.2