Pass interrupt as a callback to Suspension (#8)

This swaps `interrupt()` as a method on `Driver` for `createSuspension()`, which accepts the currently active event loop fiber and passes the interrupt function as a cached closure to the `Suspension` constructor.

Author: trowski

src/EventLoop.php

@@ -367,7 +367,7 @@ public static function createSuspension(): Suspension
             self::$fiber = self::createFiber();
         }
 
-        return new Suspension(self::getDriver(), self::$fiber);
+        return self::getDriver()->createSuspension(self::$fiber);
     }
 
     /**

src/EventLoop/Driver.php

@@ -30,16 +30,13 @@ public function run(): void;
     public function stop(): void;
 
     /**
-     * Interrupts the event loop and continues with {main}.
+     * Create an object used to suspend and resume execution, either within a fiber or from {main}.
      *
-     * The driver MUST check for a set interrupt after invoking an event callback or microtask. If an interrupt exists,
-     * it must be reset, and the driver must suspend with the given callback, i.e. call \Fiber::suspend($callback);
+     * @param \Fiber $scheduler Fiber containing the running event loop.
      *
-     * @param callable $callback Callback to run on {main} before continuing.
-     *
-     * @internal This API is only supposed to be called by the Suspension API.
+     * @return Suspension
      */
-    public function interrupt(callable $callback): void;
+    public function createSuspension(\Fiber $scheduler): Suspension;
 
     /**
      * @return bool True if the event loop is running, false if it is stopped.

src/EventLoop/Driver/TracingDriver.php

@@ -4,6 +4,7 @@
 
 use Revolt\EventLoop\Driver;
 use Revolt\EventLoop\InvalidCallbackError;
+use Revolt\EventLoop\Suspension;
 
 final class TracingDriver implements Driver
 {
@@ -36,9 +37,9 @@ public function stop(): void
         $this->driver->stop();
     }
 
-    public function interrupt(callable $callback): void
+    public function createSuspension(\Fiber $scheduler): Suspension
     {
-        $this->driver->interrupt($callback);
+        return $this->driver->createSuspension($scheduler);
     }
 
     public function isRunning(): bool

src/EventLoop/Internal/AbstractDriver.php

@@ -5,6 +5,7 @@
 use Revolt\EventLoop;
 use Revolt\EventLoop\Driver;
 use Revolt\EventLoop\InvalidCallbackError;
+use Revolt\EventLoop\Suspension;
 use Revolt\EventLoop\UnsupportedFeatureException;
 
 /**
@@ -46,6 +47,8 @@ abstract class AbstractDriver implements Driver
     /** @var callable|null */
     private $interrupt;
 
+    private \Closure $interruptCallback;
+
     private bool $running = false;
 
     private \stdClass $internalSuspensionMarker;
@@ -55,6 +58,8 @@ public function __construct()
         $this->internalSuspensionMarker = new \stdClass();
         $this->createCallbackFiber();
         $this->createQueueFiber();
+        /** @psalm-suppress InvalidArgument */
+        $this->interruptCallback = \Closure::fromCallable([$this, 'interrupt']);
     }
 
     /**
@@ -106,11 +111,6 @@ public function stop(): void
         $this->running = false;
     }
 
-    public function interrupt(callable $callback): void
-    {
-        $this->interrupt = $callback;
-    }
-
     /**
      * @return bool True if the event loop is running, false if it is stopped.
      */
@@ -446,6 +446,11 @@ public function unreference(string $callbackId): string
         return $callbackId;
     }
 
+    public function createSuspension(\Fiber $scheduler): Suspension
+    {
+        return new Suspension($this, $scheduler, $this->interruptCallback);
+    }
+
     /**
      * Set a callback to be executed when an error occurs.
      *
@@ -702,6 +707,11 @@ private function invokeMicrotasks(): void
         }
     }
 
+    private function interrupt(callable $callback): void
+    {
+        $this->interrupt = $callback;
+    }
+
     private function createCallbackFiber(): void
     {
         $suspensionMarker = $this->internalSuspensionMarker;

src/EventLoop/Suspension.php

@@ -2,15 +2,13 @@
 
 namespace Revolt\EventLoop;
 
-use Revolt\EventLoop;
-
 /**
  * Should be used to run and suspend the event loop instead of directly interacting with fibers.
  *
  * **Example**
  *
  * ```php
- * $suspension = Scheduler::createSuspension();
+ * $suspension = EventLoop::createSuspension();
  *
  * $promise->then(fn ($value) => $suspension->resume($value), fn ($throwable) => $suspension->throw($throwable));
  *
@@ -23,29 +21,25 @@ final class Suspension
     private \Fiber $scheduler;
     private Driver $driver;
     private bool $pending = false;
+    /** @var callable */
+    private $interrupt;
 
     /**
-     * Suspension constructor.
-     *
      * @param Driver $driver
      * @param \Fiber $scheduler
+     * @param callable $interrupt
      *
      * @internal
      */
-    public function __construct(Driver $driver, \Fiber $scheduler)
+    public function __construct(Driver $driver, \Fiber $scheduler, callable $interrupt)
     {
         $this->driver = $driver;
+        $this->scheduler = $scheduler;
+        $this->interrupt = $interrupt;
         $this->fiber = \Fiber::getCurrent();
 
-        if ($this->fiber === $scheduler) {
-            throw new \Error(\sprintf(
-                'Cannot call %s() within a scheduler microtask (%s::queue() callback)',
-                __METHOD__,
-                EventLoop::class,
-            ));
-        }
-
-        $this->scheduler = $scheduler;
+        // User callbacks are always executed outside the event loop fiber, so this should always be false.
+        \assert($this->fiber !== $this->scheduler);
     }
 
     public function throw(\Throwable $throwable): void
@@ -60,7 +54,7 @@ public function throw(\Throwable $throwable): void
             $this->driver->queue([$this->fiber, 'throw'], $throwable);
         } else {
             // Suspend event loop fiber to {main}.
-            $this->driver->interrupt(static fn () => throw $throwable);
+            ($this->interrupt)(static fn () => throw $throwable);
         }
     }
 
@@ -76,7 +70,7 @@ public function resume(mixed $value): void
             $this->driver->queue([$this->fiber, 'resume'], $value);
         } else {
             // Suspend event loop fiber to {main}.
-            $this->driver->interrupt(static fn () => $value);
+            ($this->interrupt)(static fn () => $value);
         }
     }