Await_kernel.AwaitSourceAbstract implementation of unbounded awaiting.
Operations that need to block the current thread for an unbounded amount of time take an Await.t which provides an implementation of awaiting for them to use.
In practice, code which needs an Await.t should get one out of an implementation of concurrency by calling Concurrent.await.
Any awaiting operation can be terminated by the awaiting implementation, which results in a Terminated exception being raised.
Under the hood, an Await.t is just a Sync.t and a Terminator.t. Since Await.t is intended to be used for blocking for an unbounded period of time, it's important to make sure that if the thread that we're waiting on exits or is terminated, this thread is also terminated.
Represents the capability to block for an unbounded amount of time.
Terminated is the exception indicating that an operation has been terminated.
terminator t is the terminator associated with t. Awaiting operations should attempt to cancel themselves if they have been terminated, raising Terminated if they succeed in doing so.
sync t is the implementation of synchronizing associated with t
val await :
t @ local ->
on_terminate:Trigger.Source.t ->
on:Trigger.t ->
Base.unit @@ portableawait t ~on_terminate ~await_on will use t to attach on_terminate to be signalled on termination and to wait until await_on has been signaled.
Note that the on_terminate trigger may not be used by await. The await_on trigger will be used before await returns.
await_until_terminated t trigger is equivalent to await t ~on_terminate:(Trigger.source trigger) ~await_on:trigger.
val await_until_terminated_or_canceled :
t @ local ->
Cancellation.t @ local ->
Trigger.t ->
Base.unit @@ portableawait_until_terminated_or_canceled t c trigger is like await_until_terminated t trigger except it will also return in case the cancellation token has been cancelled .
val await_with_terminate :
t @ local ->
Trigger.t ->
terminate:('r @ unique once portable contended -> Base.unit) @ once portable ->
'r @ unique once portable contended ->
Base.unit @@ portableawait_with_terminate t trigger ~terminate r will attach a trigger to call terminate r to the terminator of t and wait until trigger has been signalled.
The caller must always check for the reason that this call returned and act accordingly. In particular, it is possible that both the operation being awaited upon has completed successfully and that the terminator has been terminated.
val await_with_terminate_or_cancel :
t @ local ->
Cancellation.t @ local ->
Trigger.t ->
terminate_or_cancel:
('r @ unique once portable contended -> Base.unit) @ once portable ->
'r @ unique once portable contended ->
Base.unit @@ portableawait_with_terminate_or_cancel t c trigger ~terminate_or_cancel r will attach a trigger to call terminate_or_cancel r to both the terminator of t and to the given cancellation token c and then wait until trigger has been signalled.
The caller must always check for the reason that this call returned and act accordingly. In particular, it is possible that both the operation being awaited upon has completed successfully and that the terminator has been terminated or the cancellation token has been canceled or both.
is_terminated t is Terminator.is_terminated (terminator t).
with_terminator t new_terminator is an awaiter u like t where terminator u is new_terminator.
The main use case of with_terminator is to protect a blocking operation from being terminated by replacing the terminator with Terminator.unkillable:
blocking_operation (with_terminator t Terminator.unkillable)await_never_terminated t trigger is await_until_terminated (with_terminator t Terminator.unkillable) trigger.
check_terminated t checks whether the terminator of t has been terminated.
yield t yields to the scheduler using the implementation of yielding associated with t.
is_canceled t c is Cancellation.is_canceled c ~terminator:(terminator t).
val check_canceled :
t @ local ->
Cancellation.t @ local ->
Base.unit Or_canceled.t @@ portablecheck_canceled t c is Cancellation.check c ~terminator:(terminator t).