Support Promise cancellation

[clue]

Implementation is relatively straight forward, but non-trivial, considering the number of required test cases.

[clue]

Some pseudo code (only for the reference):

    $deferred = new Deferred(function ($resolve, $reject) use (&$timer, $loop, $promise) {
        // try to cancel() the given promise (only available for *some* promises)
        // this will *usually* reject the promise, but there's no guarantee
        if ($promise instanceof CancellablePromise) {
            $promise->cancel();
        }

        // explicitly stop the timer and reject the resulting promise
        // canceling the inner promise may already have cancelled the resulting promise
        $loop->cancelTimer($timer);
        $reject(new \RuntimeException('Promise cancelled'));
    });

[clue]

Cancellation support requires the Promise v2.2 API. Other versions should be supported in a way that cancellation is not available (has no effect).

Cancellation support for resolve() and reject() is straight forward.

[clue]

Cancellation support for timeout() is slightly more complicated.

I think we agree on this:

• Cancelling the input promise should be possible (irrespective of the timeout handling)
• Once the timer fires, the input promise should be cancelled and the result rejected (as discussed in Do not cancel promise once timeout fires #9, also the current behavior)

Cancelling the resulting timeout promise should also be possible (this has no effect as of yet).
The effect on the resulting timeout promise is pretty easy: abort all timers and reject with an Exception describing the cancellation.

However, it's a bit unclear which effect this should have on the input promise.

Two options:

• Only cancel the resulting timeout promise but leave the input promise alone
• Cancelling the timeout promise should also cancel the input promise

I guess both might have valid uses?

[clue]

Example code:

$input = fetchFromRemoteApi();
$timeout = Timer\timeout($input, 5.0, $loop);

$timeout->cancel();

The $timeout promise should be cancelled and rejected.

Should the $input promise be cancelled and rejected?

Two possible interpretations:

• We cancelled only the timeout timer: $input should be left alone
• We cancelled the whole operation: $input should also be cancelled (and possibly rejected)

[clue]

Let's consider some use cases where the timeout() function will be used in the real world.

Here's a gist of how a TimeoutConnector could possibly work: https://gist.github.com/clue/75d00d9c2ca2e931661c#file-timeoutconnector-php-L20

In cases like these, it's probably safe to assume that if you cancel the resulting $timeout promise, the $input promise should also be cancelled.

As such, I'm voting for making this the default.

I'm still curious if we come up with some use cases where the other behavior makes sense.

[jsor]

I also had the idea that $timeout->cancel() means, cancel the timeout ( == remove the timer). For the example gist that would mean, connect without a timeout. But i think that this really doesn't make sense. I'd consider the cancel() call as the usual "i'm not longer interested in the result", ergo cancel also the input promise.

[clue]

Thanks for the feedback @jsor!

I think we agree here. I guess the confusion can be cleared up by providing some documentation (see #14).

I've just filed PR #13 as discussed above, care to review?

I'd like to make this ticket actionable. IMO we should focus on the main use case here and close the ticket once the PR lands. The other use case can be addressed in a separate ticket once deemed useful.