Background

[ForbesLindesay]

Cancellation has not yet been put into any of the major JavaScript promise libraries as far as I'm aware.

The only promise library to have any cancellation support is when.js. There has however also been some prior art in the form of C# cancellation tokens. There are a few things to decide upon.

Triggering Cancellation

We need to decide how cancellation is triggered. This is probably as simple as a cancel method on the returned promise. The only problem with doing that is you can't then give a promise (as the result of a function) to multiple mutually suspicious receivers. C# does it with a separate CancellationTokenSource object. The relation between CancellationToken and CancellationTokenSource is analogous to the relationship between promise and resolver.

Handling Cancellation

It is easy enough to cancel the resolution of the promise, but there also needs to be a way to handle cancellation of the underlying operation (e.g. downloading a file from a web server). C# provides a CancellationToken to the function, which has methods for testing whether cancellation has been requested and for adding an event handler to be triggered when the operation is cancelled.

Propagating cancellation

Cancellation should propagate to any underlying asyncronous operations. This process has to be controlled carefully though, because there may be points where you don't want to support cancellation. C# supports cancellation by letting you simply pass on the CancellationToken to another asynchronous operation.

Correct Behaviour

When a task is cancelled in C# it is rejected with an OperationCancelledException. Alternatives would be to simply never resolve the promise, or resolve the promise imediately with undefined or null. It could also be thought of as an additional state (pending/fulfilled/rejected/cancelled)

[domenic]

I think when.js has cancellation. I'll let @briancavalier explain.

The main problem with cancellation that @kriskowal and I have considered is that cancelling provides a communication channel going from the promise to its resolver, representing a capability leak. Before, you could hand out promises to mutually-suspicious parties. With a cancelable promise, each party can affect the other party's operation, which is bad.

@wycats and @slightlyoff think of cancellation as a "fourth state," i.e. pending/fulfilled/rejected/cancelled. That is, it's a third path alongside fulfilled and rejected that a promise can take. This doesn't make much sense to me, because it has no synchronous analog. (For example, how would taskjs handle this third state.) But it's a POV that's worth representing.

[ForbesLindesay]

I've updated my original post to incorporate some of @domenic's points.

[slightlyoff]

Cancellation absolutely has a synchronous analog (typed exception handling), it just doesn't have syntax in JS. You wind up building a tiny ad-hoc protocols for it which inevitably wind up being incompatible with other's version of the same thing. This implies that not only do you need it, you need it to be part of any standard you build.

[domenic]

@slightlyoff for me the killer question is "what would taskjs do with a cancellation state." If there's no good answer to that, it doesn't seem very tenable.

On the other hand, I haven't looked much at how Microsoft's Task<T> (promise analog) handles cancellation, as @ForbesLindesay has.

In short Task<T> plus await/async keywords is much like promises + taskjs, so since Task<T> does support cancellation as @ForbesLindesay describes, I'm curious how it combines with async/await. Do you have to just abandon the keywords and drop back to raw Task<T> handling?

[briancavalier]

@slightlyoff I was just writing something similar about typed exceptions. @domenic I'm not familiar enough yet with task.js to address what cancellation might mean there.

As for when.js, it takes a pretty simple approach and models cancellation as a rejection. So, a cancelable deferred can be created with a cancelation handler that will run (before all other handlers) when the deferred is cancelled (by calling deferred.cancel()), and is allowed to return a cancelation value. That value is then used to reject the deferred's promise. So, from that point on, cancellation behaves exactly like a rejection.

That approach was roughly based Dojo Deferred's cancelation mechanism. I have to be honest and say that while it does get some usage, it's fairly limited compared to other features, so it's hard for me to say whether it's "right" or not, but it has worked out for the folks who are using it.

I've had requests to also add the cancel() method to the promise, which I've resisted because it seems very wrong: it would allow promise consumers to interfere with one another--it's a rejection, after all.

[skaegi]

I sort of agree with the idea that canceling is like exception handling with similar unwinding the stack considerations for promise chains, but I think one difference is that the user initiating cancel is outside the stack. I'm not sure what the synchronous analog for that is? Thread.interrupt?

a late comment now but...
Dojo has cancel and here's the reference -- http://dojotoolkit.org/reference-guide/1.8/dojo/Deferred.html.

Orion Deferred (https://github.com/eclipse/orion.client/blob/master/bundles/org.eclipse.orion.client.core/web/orion/Deferred.js) also supports "cancel" and we have some practical experience with it. We use use it primarily for cancelling long running operations like search and compile tasks and it does work for us. We were supporting "cancelation" primarily to retain functionality our users previously had in Dojo but we were always unsure if the cancel behavior is spec'ed correctly. In particular we found getting the promise chain canceling to work correctly a challenge and although it works for us could do with some guidelines.

Also, the considerations around capability leak are also completely valid and a real concern to us. We currently working around this problem by returning promises with empty cancel methods. It might be better if the underlying Deferred could optionally choose to react to the cancel request but that might just be an implementation detail.

[kriskowal]

Rather than creating another state, cancelation should be modeled as a subtype of rejection. As @slightlyoff hints, we should specify the type so head the ad hoc protocols off at the pass. My recommendation is that cancelation be modeled as a rejection with an Error with a true canceled property. Thus, on the consumer side:

promise.catch(function (error) {
    if (error.canceled) {
        // ...
    } else {
        // ...
    }
})

On the producer side, a a convenience:

resolver.cancel(message_opt)

[kriskowal]

My present notion for cancelation is to create a Cancelable from a promise/resolver pair. The Cancelable would look like a Promise and a Promise would look like a Cancelable to a consumer, so the consumer can write code agnostic to whether they have the right to cancel.

The Cancelable would have the elevated right to reject. However, it would also have an internal refcount and could be "forked". "fork" would produce a new Cancelable with the right to drop the refcount of the parent cancelable by one and only one when its "cancel" is called. When the refcount drops to zero, it would reject the promise with an Error with a canceled property. Otherwise, the Cancelable would serve as a proxy for the Promise.

A general Promise would have noop methods "fork" and "cancel".

For convenience, Promises and promise-alikes would have a "cancelable(cancel)" method which would produce a Cancelable proxying the promise and adding a cancelation routine. The cancel function would receive the wrapped promise as this or an argument so it could forward the cancelation to the source.

This is at least the experiment I’m entertaining for the next rev of Q. It has not proven itself in the wild.

[briancavalier]

@kriskowal That seems like a fairly complex approach (3 new methods, plus ref-counting). Do you have use cases in mind that are driving you in that direction?

[ForbesLindesay]

C# treats it as a rejection so it's as if you threw an OperationCancelledException where the await is. It can then be handled in a try-catch block.

[domenic]

As in promises-aplus/progress-spec#1 (comment) I point out that we can use the name property of the error to get cross-library distinguished error types. Seems a bit nicer than reason.canceled.

[slightlyoff]

How is taskjs now the gold standard for what we should do? Honestly, it's just doubling-down on the Python/ES6 mistake of exceptions for Generator control flow in the first place...this can't be our mental model for how we proceed. It's nuts.

Either you want Promises/Futures as a way for programmers to communicate about operation completion, or you want a concurrency mechanism. It can't be both. Which is it?

[domenic]

How is taskjs now the gold standard for what we should do?

The idea is that consuming promises with then is a stopgap until we have language-level support for shallow coroutines, either through generators in the ES6 timeframe, or hopefully through an async/await-type mechanism (as Luke Hoban and other TC39 members suggest) in the ES7 timeframe.

Promises are still valuable as a first-class object, so you can e.g. join on them or pass them between layers of abstraction. But forcing code into continuation passing style is a stopgap, and "taskjs" is our shorthand for "the shallow coroutine future." Thus if there are aspects of promises that can't be consumed using shallow coroutines, they become more awkward, forcing you to switch your ES6- and ES7-era code into ES5-style once you start needing those features.

"taskjs" is also used by us as a useful reminder that promises are designed as an asynchronous parallel to synchronous control flow, and not as simply event aggregators or "ways to communicate about operation completion." (This is seen in e.g., the return value/fulfillment value and rejection reason/thrown exception parallel, the single-resolution invariant and its corresponding functions-must-return-or-throw-but-not-both invariant, etc. I'm sure we've all read my essay on the subject, so I won't belabor the point.) So again, if there are aspects of promises that are not captured by a synchronous parallel, then we are uneasy with them. And saying "taskjs" is a way of invoking this analogy with the force of a real implementation behind it.

This is why e.g. progress invokes such uneasiness, and we are trying here to model cancellation in terms of rejections, since they have a clear synchronous parallel and thus could be consumed in "taskjs" (i.e. in "the shallow coroutine future").

[dherman]

Honestly, it's just doubling-down on the Python/ES6 mistake of exceptions for Generator control flow in the first place...this can't be our mental model for how we proceed. It's nuts.

This is just not true. At all. With ES6 generators, task.js never needs to use exceptions for control flow. If you're responding to the TaskResult thingy, that's a temporary stopgap because SpiderMonkey (the only engine to support generators so far) doesn't yet support returning a value from a generator function. But other than that, when you use task.js you never use exceptions for control flow.

Either you want Promises/Futures as a way for programmers to communicate about operation completion, or you want a concurrency mechanism. It can't be both.

That doesn't even make sense. Communicating about operation completion is a concurrency mechanism.

Dave

[dherman]

I think I may have jumped in prematurely and missed some important context (sorry!). Alex, I think you're arguing that cancellation should not be performed via rejection, and the "doubling-down" point is more of an analogy—which I happen to disagree with, but I think it's not the main point.

In fact, task.js doesn't currently unify cancel and reject. For example, the choose operation takes multiple promises and picks the first fulfilled result and then cancels all the others:

https://github.com/mozilla/task.js/blob/master/lib/task.js#L301

Pretty sure I agree with Alex that cancellation doesn't need to and shouldn't be unified with rejection. But I don't think it's relevant whether you think the StopIteration protocol is "nuts." I don't—I understand the objection, but all the alternatives I've seen suck, each in its own way—but it's really not what we're talking about.

Dave