Module Await_kernel.Trigger

A trigger represents the ability to await for or react to a signal.

To use a trigger, one creates a trigger and arranges for signal to be called on the source of the trigger.

To use a trigger to react to a signal, one may call on_signal to register a callback with the trigger. Only a single callback can be registered with each trigger. Because the registered callback may be called from an unknown context, the callback should be essentially wait-free and should not raise exceptions.

The most common way to use a trigger is to await on it with an Await.t. To do so, one must not register an action with the sink: the scheduler will instead register its own callback to resume the awaiter.

module Source : sig ... end
type t

t is the type of triggers. A sink can be used to register a callback with the associated trigger.

val is_signalled : t @ local -> bool @@ portable

is_signalled t is true if t has been signalled and false if it is unsignalled.

val on_signal : t @ local -> (f:('k @ unique once portable contended -> unit) @ once portable -> ('k @ unique once portable contended -> 'k or_null @ unique once portable contended) @ local once) @ local @@ portable

on_signal t ~f k registers f k to be run when t is signalled. It is Null if t was unsignalled and the function was registered. It is This k if t was already signalled and so the function was not registered.

Only one callback can be registered with a trigger: on_signal t f k raises Failure if t already has a registered callback.

val drop : t @ local -> bool @@ portable

drop t unregisters the callback registered with t and marks t as signalled. It is true if t was previously unsignalled and a callback was successfully unregistered. It is false if t was already signalled.

This should only be used after a callback has been registered: drop t raises Failure if t is unsignalled and there was no registered callback.

val create : unit -> t @@ portable

create () creates a new unsignalled trigger.

If a trigger is potentially added to a cancellation or termination token, then the trigger must be used. To use a trigger, either Source.signal or drop must be called on it.

val create_with_action : f:('k @ unique once portable contended -> unit) @ once portable -> ('k @ unique once portable contended -> t) @ once @@ portable

create_with_action ~f k creates a new trigger that already has the given f and resource k registered with it.

If a trigger is potentially added to a cancellation or termination token, then the trigger must be used. To use a trigger, either Source.signal or drop must be called on it.

Equivalent to:

  let create_with_action action k =
    let trigger = create () in
    let _ : bool = on_signal trigger action k in
    trigger
  ;;
val source : t -> Source.t @@ portable

source t returns the associated source of the trigger t.