Module Lwt_canceler
Lwt_canceler
Lwt-canceler is a library for synchronizing cancellation of tasks and clean-up of associated resources in Lwt.
States and transitions
type t
A
Lwt_canceler.t
is a synchronization object that can be in either of threestate
s: waiting, canceling, and canceled.- When the synchronization object is waiting, you can attach callbacks using
on_cancel
. - When the synchronization object is waiting, you can trigger the cancellation using
cancel
, doing so changes the state of the synchronization object into canceling and triggers the execution of the attached callbacks. - When the callbacks have finished executing, the synchronization object's state changes to canceled
- When the synchronization object is waiting, you can attach callbacks using
type state
=
|
Waiting
|
Canceling
|
Canceled
|
Canceled_with_exception
The
state
of a canceler. It is as described in the documentation of the typet
. The stateCanceled_with_exception
indicates that the canceler has been canceled but that exceptions have been raised during execution of the callbacks.The exceptions raised during the execution of the callbacks are only available to the first caller of
cancel
. The reasons for this are detailed in the documentation ofcancel
.
val create : unit -> t
create ()
returns a canceler in waiting state.
val cancel : t -> (unit, exn list) Stdlib.result Lwt.t
cancel t
triggers the cancellation process and returns a promisep
:t
changes state to canceling,- the callbacks attached to
t
execute sequentially in the order they were attached, - when the callbacks have all been executed,
t
changes state to canceled andp
resolves.
If
t
is in canceling state,cancel t
returns a promise that resolves whent
changes state to canceled. The call has no side-effects.If
t
is already in canceled state,cancel t
returns an already resolved promise.If all the callbacks execute without raising exceptions and their promises are resolved successfully, then the promise returned by
cancel
resolves successfully withOk ()
.If one or more of the attached callbacks raise exceptions or return promises that become rejected, the promise returned by one of the caller of
cancel
resolves toError excs
whereexcs
is the (non-empty) list of exceptions that were raised. The promise returns by the other callers ofcancel
return a promise that resolve toError []
. This result indicates to these other callers that errors occurred but that they are not responsible for handling them.The aim of this error management strategy is to ensure that errors are treated only once: one caller is responsible for handling the errors (closing some open file descriptors, freeing a lock, etc.), the others callers are not.
Callbacks
val on_cancel : t -> (unit -> unit Lwt.t) -> unit
on_cancel t callback
, ift
is in waiting state, attachescallback
tot
.When
t
becomes canceling, the callbacks are called sequentially, in FIFO order (meaning that the last callback added is executed last).If one of the callback fails (i.e., if the promise returned by one of the callbacks is rejected), the following callbacks are executed nonetheless.
If one or more of the callbacks fail, then the first call to
cancel
returnsError _
as described above.If
t
is in canceling or canceled state,on_cancel t
is a no-op.
State inspection
val canceling : t -> bool
canceling t
istrue
ifft
is canceled or canceling.
val when_canceling : t -> unit Lwt.t
when_canceling t
is a promise that is fulfilled whent
enters the canceling state. Ift
is already in the canceling or canceled state, then the promise is already fulfilled.
val canceled : t -> bool
canceled t
istrue
ifft
is canceled.
val when_canceled : t -> (unit, exn list) Stdlib.result Lwt.t
when_canceled t
is a promise that is fulfilled whent
enters the canceled state. Ift
is already in the canceled state, then the promise is already fulfilled.It is fulfilled with the value
Ok ()
if the callbacks attached tot
did not raise any exception, it is fulfilled withError []
otherwise. Checkcancel
for additional information about error management.