diff --git a/dev/moonpool/Moonpool/Background_thread/For_runner_implementors/index.html b/dev/moonpool/Moonpool/Background_thread/For_runner_implementors/index.html new file mode 100644 index 00000000..681bb222 --- /dev/null +++ b/dev/moonpool/Moonpool/Background_thread/For_runner_implementors/index.html @@ -0,0 +1,8 @@ + +For_runner_implementors (moonpool.Moonpool.Background_thread.For_runner_implementors)

Module Background_thread.For_runner_implementors

This module is specifically intended for users who implement their own runners. Regular users of Moonpool should not need to look at it.

val create : + size:(unit -> int) -> + num_tasks:(unit -> int) -> + shutdown:(wait:bool -> unit -> unit) -> + run_async:(ls:Task_local_storage.storage -> task -> unit) -> + unit -> + t

Create a new runner.

NOTE: the runner should support DLA and Suspend_ on OCaml 5.x, so that Fork_join and other 5.x features work properly.

Key that should be used by each runner to store itself in TLS on every thread it controls, so that tasks running on these threads can access the runner. This is necessary for get_current_runner to work.

diff --git a/dev/moonpool/Moonpool/Background_thread/index.html b/dev/moonpool/Moonpool/Background_thread/index.html new file mode 100644 index 00000000..5eb626c0 --- /dev/null +++ b/dev/moonpool/Moonpool/Background_thread/index.html @@ -0,0 +1,8 @@ + +Background_thread (moonpool.Moonpool.Background_thread)

Module Moonpool.Background_thread

A simple runner with a single background thread.

Because this is guaranteed to have a single worker thread, tasks scheduled in this runner always run asynchronously but in a sequential fashion.

This is similar to Fifo_pool with exactly one thread.

include module type of Runner
type task = unit -> unit
type t

A runner.

If a runner is no longer needed, shutdown can be used to signal all worker threads in it to stop (after they finish their work), and wait for them to stop.

The threads are distributed across a fixed domain pool (whose size is determined by Domain.recommended_domain_count on OCaml 5, and simple the single runtime on OCaml 4).

val size : t -> int

Number of threads/workers.

val num_tasks : t -> int

Current number of tasks. This is at best a snapshot, useful for metrics and debugging.

val shutdown : t -> unit

Shutdown the runner and wait for it to terminate. Idempotent.

val shutdown_without_waiting : t -> unit

Shutdown the pool, and do not wait for it to terminate. Idempotent.

exception Shutdown
val run_async : ?ls:Task_local_storage.storage -> t -> task -> unit

run_async pool f schedules f for later execution on the runner in one of the threads. f() will run on one of the runner's worker threads/domains.

  • parameter ls

    if provided, run the task with this initial local storage

  • raises Shutdown

    if the runner was shut down before run_async was called.

val run_wait_block : ?ls:Task_local_storage.storage -> t -> (unit -> 'a) -> 'a

run_wait_block pool f schedules f for later execution on the pool, like run_async. It then blocks the current thread until f() is done executing, and returns its result. If f() raises an exception, then run_wait_block pool f will raise it as well.

NOTE be careful with deadlocks (see notes in Fut.wait_block about the required discipline to avoid deadlocks).

  • raises Shutdown

    if the runner was already shut down

Implementing runners

module For_runner_implementors : sig ... end

This module is specifically intended for users who implement their own runners. Regular users of Moonpool should not need to look at it.

val get_current_runner : unit -> t option

Access the current runner. This returns Some r if the call happens on a thread that belongs in a runner.

  • since 0.5
type ('a, 'b) create_args = + ?on_init_thread:(dom_id:int -> t_id:int -> unit -> unit) -> + ?on_exit_thread:(dom_id:int -> t_id:int -> unit -> unit) -> + ?on_exn:(exn -> Stdlib.Printexc.raw_backtrace -> unit) -> + ?around_task:((t -> 'b) * (t -> 'b -> unit)) -> + ?name:string -> + 'a

Arguments used in create. See create for explanations.

val create : (unit -> t, _) create_args

Create the background runner

val with_ : (unit -> (t -> 'a) -> 'a, _) create_args
diff --git a/dev/moonpool/Moonpool/index.html b/dev/moonpool/Moonpool/index.html index da3c5fea..718f3bff 100644 --- a/dev/moonpool/Moonpool/index.html +++ b/dev/moonpool/Moonpool/index.html @@ -1,5 +1,5 @@ -Moonpool (moonpool.Moonpool)

Module Moonpool

Moonpool

A pool within a bigger pool (ie the ocean). Here, we're talking about pools of Thread.t that are dispatched over several Domain.t to enable parallelism.

We provide several implementations of pools with distinct scheduling strategies, alongside some concurrency primitives such as guarding locks (Lock.t) and futures (Fut.t).

module Ws_pool : sig ... end

Work-stealing thread pool.

module Fifo_pool : sig ... end

A simple thread pool in FIFO order.

module Runner : sig ... end

Interface for runners.

module Immediate_runner : sig ... end

Runner that runs tasks immediately in the caller thread.

module Exn_bt : sig ... end

Exception with backtrace.

exception Shutdown

Exception raised when trying to run tasks on runners that have been shut down.

  • since NEXT_RELEASE
val start_thread_on_some_domain : ('a -> unit) -> 'a -> Thread.t

Similar to Thread.create, but it picks a background domain at random to run the thread. This ensures that we don't always pick the same domain to run all the various threads needed in an application (timers, event loops, etc.)

val run_async : +Moonpool (moonpool.Moonpool)

Module Moonpool

Moonpool

A pool within a bigger pool (ie the ocean). Here, we're talking about pools of Thread.t that are dispatched over several Domain.t to enable parallelism.

We provide several implementations of pools with distinct scheduling strategies, alongside some concurrency primitives such as guarding locks (Lock.t) and futures (Fut.t).

module Ws_pool : sig ... end

Work-stealing thread pool.

module Fifo_pool : sig ... end

A simple thread pool in FIFO order.

module Background_thread : sig ... end

A simple runner with a single background thread.

module Runner : sig ... end

Interface for runners.

module Immediate_runner : sig ... end

Runner that runs tasks immediately in the caller thread.

module Exn_bt : sig ... end

Exception with backtrace.

exception Shutdown

Exception raised when trying to run tasks on runners that have been shut down.

  • since NEXT_RELEASE
val start_thread_on_some_domain : ('a -> unit) -> 'a -> Thread.t

Similar to Thread.create, but it picks a background domain at random to run the thread. This ensures that we don't always pick the same domain to run all the various threads needed in an application (timers, event loops, etc.)

val run_async : ?ls:Task_local_storage.storage -> Runner.t -> (unit -> unit) -> diff --git a/dev/moonpool/Moonpool__Background_thread/index.html b/dev/moonpool/Moonpool__Background_thread/index.html new file mode 100644 index 00000000..51cee82e --- /dev/null +++ b/dev/moonpool/Moonpool__Background_thread/index.html @@ -0,0 +1,2 @@ + +Moonpool__Background_thread (moonpool.Moonpool__Background_thread)

Module Moonpool__Background_thread

This module is hidden.