Add cancellation support for resolve() and reject()

Author: clue

README.md

@@ -176,20 +176,54 @@ Timer\resolve(1.5, $loop)->then(function ($time) {
 });
 ```
 
+#### Resolve cancellation
+
+You can explicitly `cancel()` the resulting timer promise at any time:
+
+```php
+$timer = Timer\resolve(2.0, $loop);
+
+$timer->cancel();
+```
+
+This will abort the timer and *reject* with a `RuntimeException`.
+
+> Note: If you're stuck on legacy versions (PHP 5.3), then the `cancel()` method
+is not available, as the Promise cancellation API is currently only available in
+[react/promise v2.1.0](https://github.com/reactphp/promise)
+which in turn requires PHP 5.4 or up.
+
 ### reject()
 
 The `reject($time, LoopInterface $loop)` function can be used to create a new Promise
 which rejects in `$time` seconds with a `TimeoutException`.
 
 ```php
 Timer\reject(2.0, $loop)->then(null, function (TimeoutException $e) {
-    echo '
+    echo 'Rejected after ' . $e->getTimeout() . ' seconds ' . PHP_EOL;
 });
 ```
 
 This function complements the [`resolve()`](#resolve) function
 and can be used as a basic building block for higher-level promise consumers.
 
+#### Reject cancellation
+
+You can explicitly `cancel()` the resulting timer promise at any time:
+
+```php
+$timer = Timer\reject(2.0, $loop);
+
+$timer->cancel();
+```
+
+This will abort the timer and *reject* with a `RuntimeException`.
+
+> Note: If you're stuck on legacy versions (PHP 5.3), then the `cancel()` method
+is not available, as the Promise cancellation API is currently only available in
+[react/promise v2.1.0](https://github.com/reactphp/promise)
+which in turn requires PHP 5.4 or up.
+
 ### TimeoutException
 
 The `TimeoutException` extends PHP's built-in `RuntimeException`.

src/functions.php

@@ -30,10 +30,15 @@ function timeout(PromiseInterface $promise, $time, LoopInterface $loop)
 
 function resolve($time, LoopInterface $loop)
 {
-    return new Promise(function ($resolve) use ($loop, $time) {
-        $loop->addTimer($time, function () use ($time, $resolve) {
+    return new Promise(function ($resolve) use ($loop, $time, &$timer) {
+        // resolve the promise when the timer fires in $time seconds
+        $timer = $loop->addTimer($time, function () use ($time, $resolve) {
             $resolve($time);
         });
+    }, function ($resolveUnused, $reject) use (&$timer, $loop) {
+        // cancelling this promise will cancel the timer and reject
+        $loop->cancelTimer($timer);
+        $reject(new \RuntimeException('Timer cancelled'));
     });
 }
 

tests/FunctionRejectTest.php

@@ -1,6 +1,7 @@
 <?php
 
 use React\Promise\Timer;
+use React\Promise\CancellablePromiseInterface;
 
 class FunctionRejectTest extends TestCase
 {
@@ -19,4 +20,17 @@ public function testPromiseWillBeRejectedOnTimeout()
 
         $this->expectPromiseRejected($promise);
     }
+
+    public function testCancelingPromiseWillRejectTimer()
+    {
+        $promise = Timer\reject(0.01, $this->loop);
+
+        if (!($promise instanceof CancellablePromiseInterface)) {
+            $this->markTestSkipped('Outdated Promise API');
+        }
+
+        $promise->cancel();
+
+        $this->expectPromiseRejected($promise);
+    }
 }

tests/FunctionResolveTest.php

@@ -1,6 +1,7 @@
 <?php
 
 use React\Promise\Timer;
+use React\Promise\CancellablePromiseInterface;
 
 class FunctionResolveTest extends TestCase
 {
@@ -19,4 +20,43 @@ public function testPromiseWillBeResolvedOnTimeout()
 
         $this->expectPromiseResolved($promise);
     }
+
+    public function testWillStartLoopTimer()
+    {
+        $loop = $this->getMock('React\EventLoop\LoopInterface');
+        $loop->expects($this->once())->method('addTimer')->with($this->equalTo(0.01));
+
+        Timer\resolve(0.01, $loop);
+    }
+
+    public function testCancellingPromiseWillCancelLoopTimer()
+    {
+        $loop = $this->getMock('React\EventLoop\LoopInterface');
+
+        $timer = $this->getMock('React\EventLoop\Timer\TimerInterface');
+        $loop->expects($this->once())->method('addTimer')->will($this->returnValue($timer));
+
+        $promise = Timer\resolve(0.01, $loop);
+
+        if (!($promise instanceof CancellablePromiseInterface)) {
+            $this->markTestSkipped('Outdated Promise API');
+        }
+
+        $loop->expects($this->once())->method('cancelTimer')->with($this->equalTo($timer));
+
+        $promise->cancel();
+    }
+
+    public function testCancelingPromiseWillRejectTimer()
+    {
+        $promise = Timer\resolve(0.01, $this->loop);
+
+        if (!($promise instanceof CancellablePromiseInterface)) {
+            $this->markTestSkipped('Outdated Promise API');
+        }
+
+        $promise->cancel();
+
+        $this->expectPromiseRejected($promise);
+    }
 }