Require Psalm 7 and declare event-loop I/O capabilities

composer.json

@@ -36,7 +36,7 @@
         "ext-json": "*",
         "phpunit/phpunit": "^9",
         "jetbrains/phpstorm-stubs": "^2019.3",
-        "psalm/phar": "6.20.*"
+        "psalm/phar": "^7.0.0-rc10"
     },
     "autoload": {
         "psr-4": {

examples/benchmark-memory.php

@@ -11,6 +11,10 @@
 
 use Revolt\EventLoop;
 use Revolt\EventLoop\Driver;
+use Revolt\EventLoop\Driver\EvDriver;
+use Revolt\EventLoop\Driver\EventDriver;
+use Revolt\EventLoop\Driver\StreamSelectDriver;
+use Revolt\EventLoop\Driver\UvDriver;
 
 require __DIR__ . '/../vendor/autoload.php';
 
@@ -21,15 +25,17 @@
 
 /** @psalm-suppress RiskyCast */
 $t  = (int) \round((\array_key_exists('t', $args) ? (int) $args['t'] : 0));
-if (\array_key_exists('d', $args)) {
-    if (\is_string($args['d'])) {
-        $loopClass = 'Revolt\EventLoop\Driver\\' . $args['d'] . 'Driver';
-        if (\class_exists($loopClass)) {
-            $loop = new ($loopClass)();
-            if ($loop instanceof Driver) {
-                EventLoop::setDriver($loop);
-            }
-        }
+if (\array_key_exists('d', $args) && \is_string($args['d'])) {
+    $loop = match ($args['d']) {
+        'Ev' => EvDriver::isSupported() ? new EvDriver() : null,
+        'Event' => EventDriver::isSupported() ? new EventDriver() : null,
+        'StreamSelect' => new StreamSelectDriver(),
+        'Uv' => UvDriver::isSupported() ? new UvDriver() : null,
+        default => null,
+    };
+
+    if ($loop instanceof Driver) {
+        EventLoop::setDriver($loop);
     }
 }
 

examples/fiber-local-automatic.php

@@ -13,12 +13,17 @@
  * This might be used to log the current URL, authenticated user, or request identifier in an HTTP server.
  *
  * @psalm-suppress UnusedProperty
+ *
+ * @psalm-mutable
  */
 final class Logger
 {
     private int $nextId = 1;
     private FiberLocal $transactionId;
 
+    /**
+     * @psalm-capabilities read-props
+     */
     public function __construct()
     {
         $this->transactionId = new FiberLocal(fn () => $this->nextId++);
@@ -29,7 +34,7 @@
      */
     public function log(string $message): void
     {
         echo $this->transactionId->get() . ': ' . $message . PHP_EOL;
     }
 }
 

examples/fiber-local-manual.php

@@ -14,10 +14,13 @@
  *
  * @psalm-suppress UnusedProperty
  */
-final class Logger
+final class ManualLogger
 {
     private FiberLocal $transactionId;
 
+    /**
+     * @psalm-capabilities read-props
+     */
     public function __construct()
     {
         $this->transactionId = new FiberLocal(fn () => throw new \Exception('Unknown transaction ID'));
@@ -41,11 +44,11 @@
      */
     public function log(string $message): void
     {
         echo $this->transactionId->get() . ': ' . $message . PHP_EOL;
     }
 }
 
-$logger = new Logger();
+$logger = new ManualLogger();
 $logger->setTransactionId(1);
 
 EventLoop::delay(1, static function () use ($logger) {

examples/http-client-suspension.php

@@ -57,9 +57,15 @@ function fetch(string $url): string
     return $buffer;
 }
 
+/**
+ * Returns the header block of an HTTP response.
+ *
+ * @psalm-pure
+ */
 function extractHeader(string $httpResponse): string
 {
     return \explode("\r\n\r\n", $httpResponse, 2)[0];
 }
 
+// Printed on the CLI, where the header is text rather than HTML.
 echo extractHeader(fetch('http://www.google.com/'));

psalm.xml

@@ -15,12 +15,6 @@
     </projectFiles>
 
     <issueHandlers>
-        <DuplicateClass>
-            <errorLevel type="suppress">
-                <directory name="examples"/>
-            </errorLevel>
-        </DuplicateClass>
-
         <InvalidOperand>
             <errorLevel type="suppress">
                 <directory name="src/EventLoop/Driver"/>
@@ -98,6 +92,19 @@
                 <file name="src/EventLoop/Driver/EventDriver.php"/>
             </errorLevel>
         </UnusedVariable>
+
+        <!-- The example prints a raw response header to the CLI. -->
+        <TaintedHtml>
+            <errorLevel type="suppress">
+                <file name="examples/http-client-suspension.php"/>
+            </errorLevel>
+        </TaintedHtml>
+
+        <TaintedTextWithQuotes>
+            <errorLevel type="suppress">
+                <file name="examples/http-client-suspension.php"/>
+            </errorLevel>
+        </TaintedTextWithQuotes>
     </issueHandlers>
 
     <stubs>

src/EventLoop.php

@@ -16,6 +16,9 @@
 /**
  * Accessor to allow global access to the event loop.
  *
+ * Scheduling and suspension are `io` for callers, like `usleep()`: the driver is the scheduler, and
+ * what other fibers do while the current one is suspended is their own effect.
+ *
  * @see Driver
  */
 final class EventLoop
@@ -35,24 +38,36 @@ public static function setDriver(Driver $driver): void
         try {
             /** @psalm-suppress InternalClass */
             self::$driver = new class () extends AbstractDriver {
+                /**
+                 * @psalm-pure
+                 */
                 #[\Override]
                 protected function activate(array $callbacks): void
                 {
                     throw new \Error("Can't activate callback during garbage collection.");
                 }
 
+                /**
+                 * @psalm-pure
+                 */
                 #[\Override]
                 protected function dispatch(bool $blocking): void
                 {
                     throw new \Error("Can't dispatch during garbage collection.");
                 }
 
+                /**
+                 * @psalm-capabilities read-props
+                 */
                 #[\Override]
                 protected function deactivate(DriverCallback $callback): void
                 {
                     // do nothing
                 }
 
+                /**
+                 * @psalm-pure
+                 */
                 #[\Override]
                 public function getHandle(): mixed
                 {
@@ -83,6 +98,9 @@ protected function now(): float
      *
      * @param \Closure(...):void $closure The callback to queue.
      * @param mixed ...$args The callback arguments.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function queue(\Closure $closure, mixed ...$args): void
     {
@@ -102,6 +120,9 @@ public static function queue(\Closure $closure, mixed ...$args): void
      *     invalidated before the callback invocation.
      *
      * @return string A unique identifier that can be used to cancel, enable or disable the callback.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function defer(\Closure $closure): string
     {
@@ -122,6 +143,9 @@ public static function defer(\Closure $closure): string
      *     before the callback invocation.
      *
      * @return string A unique identifier that can be used to cancel, enable or disable the callback.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function delay(float $delay, \Closure $closure): string
     {
@@ -142,6 +166,9 @@ public static function delay(float $delay, \Closure $closure): string
      * @param \Closure(string):void $closure The callback to repeat.
      *
      * @return string A unique identifier that can be used to cancel, enable or disable the callback.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function repeat(float $interval, \Closure $closure): string
     {
@@ -165,6 +192,9 @@ public static function repeat(float $interval, \Closure $closure): string
      * @param \Closure(string, resource):void $closure The callback to execute.
      *
      * @return string A unique identifier that can be used to cancel, enable or disable the callback.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function onReadable(mixed $stream, \Closure $closure): string
     {
@@ -188,6 +218,9 @@ public static function onReadable(mixed $stream, \Closure $closure): string
      * @param \Closure(string, resource):void $closure The callback to execute.
      *
      * @return string A unique identifier that can be used to cancel, enable or disable the callback.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function onWritable(mixed $stream, \Closure $closure): string
     {
@@ -212,6 +245,9 @@ public static function onWritable(mixed $stream, \Closure $closure): string
      * @return string A unique identifier that can be used to cancel, enable or disable the callback.
      *
      * @throws UnsupportedFeatureException If signal handling is not supported.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function onSignal(int $signal, \Closure $closure): string
     {
@@ -229,6 +265,9 @@ public static function onSignal(int $signal, \Closure $closure): string
      * @return string The callback identifier.
      *
      * @throws InvalidCallbackError If the callback identifier is invalid.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function enable(string $callbackId): string
     {
@@ -247,6 +286,9 @@ public static function enable(string $callbackId): string
      * @param string $callbackId The callback identifier.
      *
      * @return string The callback identifier.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function disable(string $callbackId): string
     {
@@ -260,6 +302,9 @@ public static function disable(string $callbackId): string
      * callback is permanently invalid. Calling this function MUST NOT fail, even if passed an invalid identifier.
      *
      * @param string $callbackId The callback identifier.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function cancel(string $callbackId): void
     {
@@ -277,6 +322,9 @@ public static function cancel(string $callbackId): void
      * @return string The callback identifier.
      *
      * @throws InvalidCallbackError If the callback identifier is invalid.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function reference(string $callbackId): string
     {
@@ -292,6 +340,9 @@ public static function reference(string $callbackId): string
      * @param string $callbackId The callback identifier.
      *
      * @return string The callback identifier.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function unreference(string $callbackId): string
     {
@@ -352,6 +403,9 @@ public static function getType(string $callbackId): CallbackType
      * @param string $callbackId The callback identifier.
      *
      * @return bool `true` if the callback is currently enabled, otherwise `false`.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function isEnabled(string $callbackId): bool
     {
@@ -364,6 +418,9 @@ public static function isEnabled(string $callbackId): bool
      * @param string $callbackId The callback identifier.
      *
      * @return bool `true` if the callback is currently referenced, otherwise `false`.
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function isReferenced(string $callbackId): bool
     {
@@ -391,6 +448,9 @@ public static function getDriver(): Driver
      * Calls from the same fiber will return the same suspension object.
      *
      * @return Suspension
+     *
+     * @psalm-capabilities io
+     * @psalm-suppress ImpureMethodCall
      */
     public static function getSuspension(): Suspension
     {
@@ -415,6 +475,8 @@ public static function run(): void
      * Disable construction as this is a static class.
      *
      * @psalm-suppress UnusedConstructor
+     *
+     * @psalm-capabilities read-props
      */
     private function __construct()
     {