From c1a4d9346d0bb87681b610191cef905909373e28 Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Mon, 24 Oct 2016 17:08:53 +0200 Subject: [PATCH 1/3] Add warning about locally closed resources being undefined behavior Also makes Loop docs consistent with Driver. Resolves #106. --- src/Loop.php | 61 +++++++++++++++++++++++++++++++-------------- src/Loop/Driver.php | 18 ++++++++++--- 2 files changed, 56 insertions(+), 23 deletions(-) diff --git a/src/Loop.php b/src/Loop.php index 92795744..fc173a25 100644 --- a/src/Loop.php +++ b/src/Loop.php @@ -178,11 +178,18 @@ public static function repeat($interval, callable $callback, $data = null) /** * Execute a callback when a stream resource becomes readable or is closed for reading. * + * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the + * watcher when closing the resource locally. Drivers might choose to notify the user in a debug mode if there are + * watchers on invalid resources, but are not required to, due to the high performance impact. Watchers on closed + * resources are therefore undefined behavior. + * + * Multiple watchers on the same stream may be executed in any order. + * * @param resource $stream The stream to monitor. * @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter. * - * @return string An identifier that can be used to cancel, enable or disable the watcher. + * @return string An unique identifier that can be used to cancel, enable or disable the watcher. */ public static function onReadable($stream, callable $callback, $data = null) { @@ -193,11 +200,18 @@ public static function onReadable($stream, callable $callback, $data = null) /** * Execute a callback when a stream resource becomes writable or is closed for writing. * + * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the + * watcher when closing the resource locally. Drivers might choose to notify the user in a debug mode if there are + * watchers on invalid resources, but are not required to, due to the high performance impact. Watchers on closed + * resources are therefore undefined behavior. + * + * Multiple watchers on the same stream may be executed in any order. + * * @param resource $stream The stream to monitor. * @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter. * - * @return string An identifier that can be used to cancel, enable or disable the watcher. + * @return string An unique identifier that can be used to cancel, enable or disable the watcher. */ public static function onWritable($stream, callable $callback, $data = null) { @@ -208,16 +222,19 @@ 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. + * Warning: Installing the 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. + * + * Multiple watchers on the same signal may be executed in any order. * * @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. + * @param mixed $data Arbitrary data given to the callback function as the $data parameter. * - * @return string An identifier that can be used to cancel, enable or disable the watcher. + * @return string An unique identifier that can be used to cancel, enable or disable the watcher. * - * @throws UnsupportedFeatureException Thrown if signal handling is not supported. + * @throws UnsupportedFeatureException If signal handling is not supported. */ public static function onSignal($signo, callable $callback, $data = null) { @@ -228,11 +245,15 @@ public static function onSignal($signo, callable $callback, $data = null) /** * Enable a watcher. * + * Watchers (enabling or new watchers) MUST immediately be marked as enabled, but only be activated (i.e. callbacks + * can be called) right before the next tick. Callbacks of watchers MUST not be called in the tick they were + * enabled. + * * @param string $watcherId The watcher identifier. * * @return void * - * @throws InvalidWatcherException Thrown if the watcher identifier is invalid. + * @throws InvalidWatcherException If the watcher identifier is invalid. */ public static function enable($watcherId) { @@ -243,6 +264,9 @@ public static function enable($watcherId) /** * Disable a watcher. * + * Disabling a watcher MUST NOT invalidate the watcher. Calling this function MUST NOT fail, even if passed an + * invalid watcher. + * * @param string $watcherId The watcher identifier. * * @return void @@ -256,8 +280,8 @@ public static function disable($watcherId) /** * Cancel a watcher. * - * This will detatch the event loop from all resources that are associated to the watcher. After this - * operation the watcher is permanently invalid. + * This will detatch the event loop from all resources that are associated to the watcher. After this operation the + * watcher is permanently invalid. Calling this function MUST NOT fail, even if passed an invalid watcher. * * @param string $watcherId The watcher identifier. * @@ -272,8 +296,8 @@ public static function cancel($watcherId) /** * Reference a watcher. * - * This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state - * by default. + * This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state by + * default. * * @param string $watcherId The watcher identifier. * @@ -290,8 +314,8 @@ public static function reference($watcherId) /** * Unreference a watcher. * - * The event loop should exit the run method when only unreferenced watchers are still being monitored. - * Watchers are all referenced by default. + * The event loop should exit the run method when only unreferenced watchers are still being monitored. Watchers + * are all referenced by default. * * @param string $watcherId The watcher identifier. * @@ -309,8 +333,7 @@ public static function unreference($watcherId) * Stores information in the loop bound registry. * * This can be used to store loop bound information. Stored information is package private. Packages MUST NOT - * retrieve the stored state of other packages. Packages MUST use the following prefix to keys: - * `vendor.package.` + * retrieve the stored state of other packages. Packages MUST use the following prefix for keys: `vendor.package.` * * @param string $key The namespaced storage key. * @param mixed $value The value to be stored. @@ -326,12 +349,12 @@ public static function setState($key, $value) /** * Gets information stored bound to the loop. * - * Stored information is package private. Packages MUST NOT retrieve the stored state of other packages. - * Packages MUST use the following prefix to keys: `vendor.package.` + * Stored information is package private. Packages MUST NOT retrieve the stored state of other packages. Packages + * MUST use the following prefix for keys: `vendor.package.` * * @param string $key The namespaced storage key. * - * @return mixed previously stored value or null if it doesn't exist + * @return mixed The previously stored value or `null` if it doesn't exist. */ public static function getState($key) { diff --git a/src/Loop/Driver.php b/src/Loop/Driver.php index 4c69389b..d0da80fc 100644 --- a/src/Loop/Driver.php +++ b/src/Loop/Driver.php @@ -80,6 +80,11 @@ abstract public function repeat($interval, callable $callback, $data = null); /** * Execute a callback when a stream resource becomes readable or is closed for reading. * + * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the + * watcher when closing the resource locally. Drivers might choose to notify the user in a debug mode if there are + * watchers on invalid resources, but are not required to, due to the high performance impact. Watchers on closed + * resources are therefore undefined behavior. + * * Multiple watchers on the same stream may be executed in any order. * * @param resource $stream The stream to monitor. @@ -93,6 +98,11 @@ abstract public function onReadable($stream, callable $callback, $data = null); /** * Execute a callback when a stream resource becomes writable or is closed for writing. * + * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the + * watcher when closing the resource locally. Drivers might choose to notify the user in a debug mode if there are + * watchers on invalid resources, but are not required to, due to the high performance impact. Watchers on closed + * resources are therefore undefined behavior. + * * Multiple watchers on the same stream may be executed in any order. * * @param resource $stream The stream to monitor. @@ -106,12 +116,12 @@ abstract public function onWritable($stream, callable $callback, $data = null); /** * Execute a callback when a signal is received. * - * Multiple watchers on the same signal may be executed in any order. - * - * NOTE: Installing the same signal on different instances of this interface is deemed undefined behavior. + * Warning: Installing the 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. * + * Multiple watchers on the same signal may be executed in any order. + * * @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. @@ -267,7 +277,7 @@ abstract public function info(); * * Example: the `uv_loop` resource for `libuv` or the `EvLoop` object for `libev` or `null` for a native driver. * - * NOTE: This function is *not* exposed in the `Loop` class. Users shall access it directly on the respective loop + * Note: This function is *not* exposed in the `Loop` class. Users shall access it directly on the respective loop * instance. * * @return null|object|resource The loop handle the event loop operates on. `null` if there is none. From 5d9de0c060279a3a53bbb0c47a37c38903abaad8 Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Mon, 24 Oct 2016 17:21:12 +0200 Subject: [PATCH 2/3] Fix typo, remove debug mode hint --- src/Loop.php | 12 ++++++------ src/Loop/Driver.php | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/Loop.php b/src/Loop.php index fc173a25..8e507489 100644 --- a/src/Loop.php +++ b/src/Loop.php @@ -179,9 +179,9 @@ public static function repeat($interval, callable $callback, $data = null) * Execute a callback when a stream resource becomes readable or is closed for reading. * * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the - * watcher when closing the resource locally. Drivers might choose to notify the user in a debug mode if there are - * watchers on invalid resources, but are not required to, due to the high performance impact. Watchers on closed - * resources are therefore undefined behavior. + * watcher when closing the resource locally. Drivers may choose to notify the user if there are watchers on invalid + * resources, but are not required to, due to the high performance impact. Watchers on closed resources are + * therefore undefined behavior. * * Multiple watchers on the same stream may be executed in any order. * @@ -201,9 +201,9 @@ public static function onReadable($stream, callable $callback, $data = null) * Execute a callback when a stream resource becomes writable or is closed for writing. * * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the - * watcher when closing the resource locally. Drivers might choose to notify the user in a debug mode if there are - * watchers on invalid resources, but are not required to, due to the high performance impact. Watchers on closed - * resources are therefore undefined behavior. + * watcher when closing the resource locally. Drivers may choose to notify the user if there are watchers on invalid + * resources, but are not required to, due to the high performance impact. Watchers on closed resources are + * therefore undefined behavior. * * Multiple watchers on the same stream may be executed in any order. * diff --git a/src/Loop/Driver.php b/src/Loop/Driver.php index d0da80fc..045db66c 100644 --- a/src/Loop/Driver.php +++ b/src/Loop/Driver.php @@ -81,9 +81,9 @@ abstract public function repeat($interval, callable $callback, $data = null); * Execute a callback when a stream resource becomes readable or is closed for reading. * * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the - * watcher when closing the resource locally. Drivers might choose to notify the user in a debug mode if there are - * watchers on invalid resources, but are not required to, due to the high performance impact. Watchers on closed - * resources are therefore undefined behavior. + * watcher when closing the resource locally. Drivers may choose to notify the user if there are watchers on invalid + * resources, but are not required to, due to the high performance impact. Watchers on closed resources are + * therefore undefined behavior. * * Multiple watchers on the same stream may be executed in any order. * @@ -99,9 +99,9 @@ abstract public function onReadable($stream, callable $callback, $data = null); * Execute a callback when a stream resource becomes writable or is closed for writing. * * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the - * watcher when closing the resource locally. Drivers might choose to notify the user in a debug mode if there are - * watchers on invalid resources, but are not required to, due to the high performance impact. Watchers on closed - * resources are therefore undefined behavior. + * watcher when closing the resource locally. Drivers may choose to notify the user if there are watchers on invalid + * resources, but are not required to, due to the high performance impact. Watchers on closed resources are + * therefore undefined behavior. * * Multiple watchers on the same stream may be executed in any order. * From 9916529f3c433ebcc32f61d09b2dd914922b5c17 Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Tue, 25 Oct 2016 17:29:09 +0200 Subject: [PATCH 3/3] =?UTF-8?q?'may'=20=E2=86=92=20'MAY',=20copy=20docs=20?= =?UTF-8?q?for=20defer,=20delay,=20repeat=20from=20Driver=20to=20Loop?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/Loop.php | 35 +++++++++++++++++++++-------------- src/Loop/Driver.php | 14 +++++++------- 2 files changed, 28 insertions(+), 21 deletions(-) diff --git a/src/Loop.php b/src/Loop.php index 8e507489..6c81530d 100644 --- a/src/Loop.php +++ b/src/Loop.php @@ -129,10 +129,14 @@ public static function stop() /** * Defer the execution of a callback. * - * @param callable(string $watcherId, mixed $data) $callback The callback to defer. + * The deferred callable MUST be executed in the next tick of the event loop and before any other type of watcher. + * Order of enabling MUST be preserved when executing the callbacks. + * + * @param callable(string $watcherId, mixed $data) $callback The callback to defer. The `$watcherId` will be + * invalidated before the callback call. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter. * - * @return string An identifier that can be used to cancel, enable or disable the watcher. + * @return string An unique identifier that can be used to cancel, enable or disable the watcher. */ public static function defer(callable $callback, $data = null) { @@ -143,13 +147,15 @@ public static function defer(callable $callback, $data = null) /** * Delay the execution of a callback. * - * The delay is a minimum and approximate, accuracy is not guaranteed. + * The delay is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be determined by which + * timers expire first, but timers with the same expiration time MAY be executed in any order. * - * @param int $time The amount of time, in milliseconds, to delay the execution for. - * @param callable(string $watcherId, mixed $data) $callback The callback to delay. + * @param int $delay The amount of time, in milliseconds, to delay the execution for. + * @param callable(string $watcherId, mixed $data) $callback The callback to delay. The `$watcherId` will be + * invalidated before the callback call. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter. * - * @return string An identifier that can be used to cancel, enable or disable the watcher. + * @return string An unique identifier that can be used to cancel, enable or disable the watcher. */ public static function delay($time, callable $callback, $data = null) { @@ -160,14 +166,15 @@ public static function delay($time, callable $callback, $data = null) /** * Repeatedly execute a callback. * - * The interval between executions is a minimum and approximate, accuracy is not guaranteed. + * The interval between executions is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be + * determined by which timers expire first, but timers with the same expiration time MAY be executed in any order. * The first execution is scheduled after the first interval period. * * @param int $interval The time interval, in milliseconds, to wait between executions. * @param callable(string $watcherId, mixed $data) $callback The callback to repeat. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter. * - * @return string An identifier that can be used to cancel, enable or disable the watcher. + * @return string An unique identifier that can be used to cancel, enable or disable the watcher. */ public static function repeat($interval, callable $callback, $data = null) { @@ -179,11 +186,11 @@ public static function repeat($interval, callable $callback, $data = null) * Execute a callback when a stream resource becomes readable or is closed for reading. * * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the - * watcher when closing the resource locally. Drivers may choose to notify the user if there are watchers on invalid + * watcher when closing the resource locally. Drivers MAY choose to notify the user if there are watchers on invalid * resources, but are not required to, due to the high performance impact. Watchers on closed resources are * therefore undefined behavior. * - * Multiple watchers on the same stream may be executed in any order. + * Multiple watchers on the same stream MAY be executed in any order. * * @param resource $stream The stream to monitor. * @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. @@ -201,11 +208,11 @@ public static function onReadable($stream, callable $callback, $data = null) * Execute a callback when a stream resource becomes writable or is closed for writing. * * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the - * watcher when closing the resource locally. Drivers may choose to notify the user if there are watchers on invalid + * watcher when closing the resource locally. Drivers MAY choose to notify the user if there are watchers on invalid * resources, but are not required to, due to the high performance impact. Watchers on closed resources are * therefore undefined behavior. * - * Multiple watchers on the same stream may be executed in any order. + * Multiple watchers on the same stream MAY be executed in any order. * * @param resource $stream The stream to monitor. * @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. @@ -223,10 +230,10 @@ public static function onWritable($stream, callable $callback, $data = null) * Execute a callback when a signal is received. * * Warning: Installing the 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 + * 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. * - * Multiple watchers on the same signal may be executed in any order. + * Multiple watchers on the same signal MAY be executed in any order. * * @param int $signo The signal number to monitor. * @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute. diff --git a/src/Loop/Driver.php b/src/Loop/Driver.php index 045db66c..0a22cb79 100644 --- a/src/Loop/Driver.php +++ b/src/Loop/Driver.php @@ -66,7 +66,7 @@ abstract public function delay($delay, callable $callback, $data = null); * Repeatedly execute a callback. * * The interval between executions is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be - * determined by which timers expire first, but timers with the same expiration time may be executed in any order. + * determined by which timers expire first, but timers with the same expiration time MAY be executed in any order. * The first execution is scheduled after the first interval period. * * @param int $interval The time interval, in milliseconds, to wait between executions. @@ -81,11 +81,11 @@ abstract public function repeat($interval, callable $callback, $data = null); * Execute a callback when a stream resource becomes readable or is closed for reading. * * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the - * watcher when closing the resource locally. Drivers may choose to notify the user if there are watchers on invalid + * watcher when closing the resource locally. Drivers MAY choose to notify the user if there are watchers on invalid * resources, but are not required to, due to the high performance impact. Watchers on closed resources are * therefore undefined behavior. * - * Multiple watchers on the same stream may be executed in any order. + * Multiple watchers on the same stream MAY be executed in any order. * * @param resource $stream The stream to monitor. * @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. @@ -99,11 +99,11 @@ abstract public function onReadable($stream, callable $callback, $data = null); * Execute a callback when a stream resource becomes writable or is closed for writing. * * Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the - * watcher when closing the resource locally. Drivers may choose to notify the user if there are watchers on invalid + * watcher when closing the resource locally. Drivers MAY choose to notify the user if there are watchers on invalid * resources, but are not required to, due to the high performance impact. Watchers on closed resources are * therefore undefined behavior. * - * Multiple watchers on the same stream may be executed in any order. + * Multiple watchers on the same stream MAY be executed in any order. * * @param resource $stream The stream to monitor. * @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. @@ -117,10 +117,10 @@ abstract public function onWritable($stream, callable $callback, $data = null); * Execute a callback when a signal is received. * * Warning: Installing the 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 + * 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. * - * Multiple watchers on the same signal may be executed in any order. + * Multiple watchers on the same signal MAY be executed in any order. * * @param int $signo The signal number to monitor. * @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.