Await_kernel.CancellationSourceA 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.
t is the type of cancellation tokens. Tokens become canceled by calls to Source.cancel.
is_canceled t ~terminator is true if t has been canceled and false otherwise. Once is_canceled t ~terminator is true it will never again become false.
check t ~terminator is Canceled if t has been canceled, or Completed () otherwise.
same t1 t2 determines whether the tokens t1 and t2 are the one and the same.
is_cancellable t is true if the token has an associated source and can be cancelled through it and otherwise false.
source t returns the source of the cancellation token This t or Null in case the token is not cancellable.
val with_ :
('a : value_or_null). (t @ local -> 'a @ unique once) @ local once ->
'a @ unique once @@ portablewith_ 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 : value_or_null). t @ local ->
(t @ local -> 'a @ unique once) @ local once ->
'a @ unique once @@ portablewith_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 : value_or_null). t list @ local ->
(t @ local -> 'a @ unique once) @ local once ->
'a @ unique once @@ portablewith_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.
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, orAttached 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.