Cancellation/A+ - Draft D

gistfile1.md

Cancellation/A+

This proposal specifies how cancellation is triggered and handled in a Promises/A+ library. Cancellation support is optional and provides a mechanism for a promise consumer to signal that further work on fulfilling should be stopped. Cancellation is modeled as rejection with a specified "Cancel" Error signature.

Terminology

In addition to the terminology from Promises/A+ we use the following:

1. CancelException is an error used to reject cancelled promises.
2. "direct cancellation" is what occurs when a pending promise is cancelled by the consumer of a promise by calling cancel

Requirements

The CancelException

When a promise is directly cancelled it is rejected with a CancelException error. A CancelException instance must obey the following criteria:

1. It must be an instance of Error (cancelException instanceof Error === true).
2. It must have a name property with value "Cancel".

The cancel Method

The cancel method attempts to prevent a pending promise from completing normally. In order for a promise to be succesfully direcly cancelled it must be both pending and support cancellation otherwise the call has no effect. The cancel method accepts no arguments and returns the promise:

promise.cancel();

1. If the promise is not pending or does not support cancellation the call returns the promise immediately.
2. Otherwise, the promise is rejected with a CancelException and the promise returned.

then promises and cancellation