Module Await_kernel.Cancellation

A cancellation token represents an explicit, expected, and voluntary submission or desire to be interrupted asynchronously.

Operations that potentially block or take a long time may take an explicit cancellation token as a parameter to allow such operations to be interrupted and canceled. Canceled operations should still return normally, as opposed to raising an exception, perhaps using the Or_canceled.t type to indicate that they have been canceled.

Tokens can be created that are linked to a token from some outer level scope of the program. This way an individual operation or sequence of operations can be canceled independently of the outer level token while also respecting the cancelation of the outer level token.

To implement a cancellable operation, one can poll the token or temporarily add triggers to the token using add_trigger.

type t

t is the type of cancellation tokens. Tokens become canceled by calls to Source.cancel.

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

is_canceled t is true if t has been canceled and false otherwise. Once is_canceled t is true it will never again become false.

val check : t @ local -> unit Or_canceled.t @@ portable

check t is Canceled if t has been canceled, or Completed () otherwise.

val same : t @ local -> (t @ local -> bool) @ local @@ portable

same t1 t2 determines whether the tokens t1 and t2 are the one and the same.

val never : t @@ portable

never is a cancellation token that can never be canceled.

val always : t @@ portable

always is a cancellation token that is already canceled.

module Source : sig ... end
val is_cancellable : t @ local -> bool @@ portable

is_cancellable t is true if the token has an associated source and can be cancelled through it and otherwise false.

val source : t @ local -> Source.t or_null @@ portable

source t returns the source of the cancellation token This t or Null in case the token is not cancellable.

val with_ : 'a. (t @ local -> 'a) @ local once -> 'a @@ portable

with_ f creates a fresh cancellation token and passes it to f. The token is canceled when Source.cancel has been called on the source.

Panics if t still has unsignaled attached triggers when f finishes.

val with_linked : 'a. t @ local -> ((t @ local -> 'a) @ local once -> 'a) @ local @@ portable

with_linked t f creates a fresh cancellation token linked to t and passes it to f. The token is canceled when either t is canceled or Source.cancel has been called on the source.

Panics if t still has unsignaled attached triggers when f finishes.

val with_linked_multi : 'a. t list @ local -> ((t @ local -> 'a) @ local once -> 'a) @ local @@ portable

with_linked_multi ts f creates a fresh cancellation token and passes it to f. The token is canceled when any of ts are canceled or when Source.cancel has been called on the source.

Panics if t still has unsignaled attached triggers when f finishes.

val add_trigger : t @ local -> (Trigger.Source.t -> Link.t) @ local @@ portable

add_trigger t s attaches s to the token t so that it will be signaled when t is canceled.

Returns

  • Canceled if t was already canceled and so s was not attached to it,
  • Signaled if s was already signaled and so wasn't attached to t, or
  • Attached if t was not canceled and s was not signaled and so s has been attached to t.

add_trigger does not update the trigger s. In particular, a return value of Canceled tells nothing about the state of s.

module Expert : sig ... end
module For_testing : sig ... end