package domain-local-await

Represents an asynchronous trigger.

NOTE: release and await should be domain safe and ideally optimized with the assumption that release may be called multiple times and even before await is called. Furthermore, await may be called at most once.

prepare_for_await () prepares and returns a trigger t for at most one use of t.await () by calling the prepare function registered for the current domain.

prepare_for_await and t.await are allowed to raise an (unspecified) exception that indicates that the caller's fiber has been canceled (and should terminate). If an exception is raised, then the caller should perform whatever cleanup is necessary to e.g. avoid space leaks.

NOTE: It is allowed for two different calls of prepare_for_await to return the same trigger and e.g. share a single trigger per domain or per fiber or even just have one single trigger.

using ~prepare_for_await ~while_running registers the given asynchronous trigger mechanism for the current domain, or, if the domain has been configured to use per_thread schedulers, the current systhread, for the duration of running the given scheduler. In other words, this sets the implementation of prepare_for_await for blocking under the scheduler.

NOTE: The given prepare_for_await function is called every time prepare_for_await is called while the scheduler is running.

NOTE: This is normally only called by libraries that implement schedulers and the specified prepare_for_await typically returns a trigger mechanism t that tightly integrates with the scheduler by e.g. performing an effect to suspend the current fiber when t.await is called.

Signature for a minimal subset of the Stdlib.Thread module needed by domain local await.

per_thread (module Thread) configures the current domain to store and select the trigger mechanism per systhread. This can be called at most once per domain before any calls to prepare_for_await.

The reason why this is an opt-in feature is that this allows domain local await to be implemented without depending on Thread which also depends on Unix.

Usage:

Domain.spawn @@ fun () ->
  Domain_local_await.per_thread (module Thread);

  (* ... *)

  ()
  |> Thread.create (fun () ->
     Domain_local_await.using
       ~prepare_for_await:prepare_for_scheduler_a
       ~while_running:scheduler_a);

  ()
  |> Thread.create (fun () ->
     Domain_local_await.using
       ~prepare_for_await:prepare_for_scheduler_b
       ~while_running:scheduler_b);

  (* ... *)

NOTE: It is not necessary to use per systhread configuration on a domain unless you want different systhreads to use different schedulers.