Skip to content

Commit 9f3f6b9

Browse files
committed
Add a warning/implementation note about installing handlers for a same signal on different loops
This needs to be undefined behavior as we do not have the possibilities in PHP (i.e. the language and functions don't give us the power) to distinguish properly whether a signal is already installed or not Also, when we try to set a handler for a signal we've already installed a signal elsewhere, the second onSignal() call will lead implementations to override the original handler (on the system level, with signal()/sigaction()) Ultimately some extensions just flat out emit a warning in that case (e.g. libev). Thus, we cannot control what happens and hence this needs to be specified as undefined behavior.
1 parent 8f38808 commit 9f3f6b9

File tree

2 files changed

+7
-0
lines changed

2 files changed

+7
-0
lines changed

src/Loop.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,9 @@ public static function onWritable($stream, callable $callback, $data = null)
199199
/**
200200
* Execute a callback when a signal is received.
201201
*
202+
* WARNING: Installing a handler on the same signal on different scopes of event loop execution is
203+
* undefined behavior and may break things arbitrarily.
204+
*
202205
* @param int $signo The signal number to monitor.
203206
* @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.
204207
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.

src/Loop/Driver.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,10 @@ public function onWritable($stream, callable $callback, $data = null);
100100
*
101101
* Multiple watchers on the same signal may be executed in any order.
102102
*
103+
* NOTE: Installing a same signal on different instances of this interface is deemed undefined behavior.
104+
* Implementations may try to detect this, if possible, but are not required to.
105+
* This is due to technical limitations of the signals being registered globally per process.
106+
*
103107
* @param int $signo The signal number to monitor.
104108
* @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.
105109
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.

0 commit comments

Comments
 (0)