Provide useful exception trace in TimeoutCancellationToken (#303)

Without this, the exception trace is pretty useless, because it only includes Loop::run() and other internal loop calls, giving absolutely no indication which kind of thing had a timeout.

Use debug_backtrace instead of creating the exception early, because it helps with the changes to GC behavior such a change might introduce.

Co-authored-by: Aaron Piotrowski <aaron@trowski.com>

lib/TimeoutCancellationToken.php

@@ -2,6 +2,8 @@
 
 namespace Amp;
 
+use function Amp\Internal\formatStacktrace;
+
 /**
  * A TimeoutCancellationToken automatically requests cancellation after the timeout has elapsed.
  */
@@ -10,21 +12,24 @@ final class TimeoutCancellationToken implements CancellationToken
     /** @var string */
     private $watcher;
 
-    /** @var \Amp\CancellationToken */
+    /** @var CancellationToken */
     private $token;
 
     /**
-     * @param int $timeout Milliseconds until cancellation is requested.
+     * @param int    $timeout Milliseconds until cancellation is requested.
      * @param string $message Message for TimeoutException. Default is "Operation timed out".
      */
     public function __construct(int $timeout, string $message = "Operation timed out")
     {
         $source = new CancellationTokenSource;
         $this->token = $source->getToken();
 
-        $this->watcher = Loop::delay($timeout, static function () use ($source, $message) {
-            $source->cancel(new TimeoutException($message));
+        $trace = \debug_backtrace(\DEBUG_BACKTRACE_IGNORE_ARGS);
+        $this->watcher = Loop::delay($timeout, static function () use ($source, $message, $trace) {
+            $trace = formatStacktrace($trace);
+            $source->cancel(new TimeoutException("$message\r\nTimeoutCancellationToken was created here:\r\n$trace"));
         });
+
         Loop::unreference($this->watcher);
     }
 

test/TimeoutCancellationTokenTest.php

@@ -3,26 +3,31 @@
 namespace Amp\Test;
 
 use Amp\CancelledException;
-use Amp\Delayed;
 use Amp\Loop;
 use Amp\TimeoutCancellationToken;
 use Amp\TimeoutException;
+use function Amp\delay;
 
 class TimeoutCancellationTokenTest extends BaseTest
 {
     public function testTimeout()
     {
         Loop::run(function () {
+            $line = __LINE__ + 1;
             $token = new TimeoutCancellationToken(10);
 
             $this->assertFalse($token->isRequested());
-            yield new Delayed(20);
+            yield delay(20);
             $this->assertTrue($token->isRequested());
 
             try {
                 $token->throwIfRequested();
             } catch (CancelledException $exception) {
                 $this->assertInstanceOf(TimeoutException::class, $exception->getPrevious());
+
+                $message = $exception->getPrevious()->getMessage();
+                $this->assertContains('TimeoutCancellationToken was created here', $message);
+                $this->assertContains('TimeoutCancellationTokenTest.php:' . $line, $message);
             }
         });
     }