Merge pull request #84 from async-interop/signal_handlers_in_different_loops

Add a warning/implementation note about installing handlers for a same signal on different loops

Author: WyriHaximus

src/Loop.php

@@ -199,6 +199,9 @@ public static function onWritable($stream, callable $callback, $data = null)
     /**
      * Execute a callback when a signal is received.
      *
+     * WARNING: Installing a handler on the same signal on different scopes of event loop execution is
+     *          undefined behavior and may break things arbitrarily.
+     *
      * @param int $signo The signal number to monitor.
      * @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.

src/Loop/Driver.php

@@ -100,6 +100,10 @@ public function onWritable($stream, callable $callback, $data = null);
      *
      * Multiple watchers on the same signal may be executed in any order.
      *
+     * NOTE: Installing a same signal on different instances of this interface is deemed undefined behavior.
+     *       Implementations may try to detect this, if possible, but are not required to.
+     *       This is due to technical limitations of the signals being registered globally per process.
+     *
      * @param int $signo The signal number to monitor.
      * @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.