Lwt-canceler is a library for synchronizing cancellation of tasks and clean-up of associated resources in Lwt.
Lwt_canceler.t is a synchronization object that can be in either of three
states: waiting, canceling, and canceled.
- When the synchronization object is waiting, you can attach callbacks using
- 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
state of a canceler. It is as described in the documentation of the type
t. The state
Canceled_with_exception indicates that the canceler has been canceled but that exceptions have been raised during execution of the callbacks.
val create : unit -> t
create () returns a canceler in waiting state.
cancel t triggers the cancellation process and returns a promise
tchanges state to canceling,
- the callbacks attached to
texecute sequentially in the order they were attached,
- when the callbacks have all been executed,
tchanges state to canceled and
t is in canceling state,
cancel t returns a promise that resolves when
t changes state to canceled. The call has no side-effects.
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 with
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 to
Error excs where
excs is the (non-empty) list of exceptions that were raised. The promise returns by the other callers of
cancel return a promise that resolve to
Error . 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.
on_cancel t callback, if
t is in waiting state, attaches
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
Error _ as described above.
t is in canceling or canceled state,
on_cancel t is a no-op.
val canceling : t -> bool
canceling t is
t is canceled or canceling.
when_canceling t is a promise that is fulfilled when
t enters the canceling state. If
t is already in the canceling or canceled state, then the promise is already fulfilled.
val canceled : t -> bool
canceled t is
t is canceled.
when_canceled t is a promise that is fulfilled when
t enters the canceled state. If
t is already in the canceled state, then the promise is already fulfilled.
It is fulfilled with the value
Ok () if the callbacks attached to
t did not raise any exception, it is fulfilled with
Error  otherwise. Check
cancel for additional information about error management.