package lwt-canceler

A 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 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

The 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.

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 of cancel.

create () returns a canceler in waiting state.

cancel t triggers the cancellation process and returns a promise p:

1. t changes state to canceling,
2. the callbacks attached to t execute sequentially in the order they were attached,
3. when the callbacks have all been executed, t changes state to canceled and p resolves.

If t is in canceling state, cancel t returns a promise that resolves when t 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 with Ok ().

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 callback to t.

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 returns Error _ as described above.

If t is in canceling or canceled state, on_cancel t is a no-op.

canceling t is true iff 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.

canceled t is true iff 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.

state t is the state of t at the moment of call.