diff --git a/README.md b/README.md index 03a93a12..d98e4c73 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Here is an async HTTP server built with just the event loop. $loop = React\EventLoop\Factory::create(); $server = stream_socket_server('tcp://127.0.0.1:8080'); -stream_set_blocking($server, 0); +stream_set_blocking($server, false); $loop->addReadStream($server, function ($server) use ($loop) { $conn = stream_socket_accept($server); @@ -97,7 +97,7 @@ $loop->run(); ## Factory The `Factory` class exists as a convenient way to pick the best available -[loop implementation)(#loop-implementation). +[loop implementation](#loop-implementations). The `create(): LoopInterface` method can be used to create a new loop instance: @@ -170,14 +170,14 @@ If you want to access any variables within your callback function, you can bind arbitrary data to a callback closure like this: ```php -function hello(LoopInterface $loop, $name) +function hello($name, LoopInterface $loop) { $loop->addTimer(1.0, function () use ($name) { echo "hello $name\n"; }); } -hello('Tester'); +hello('Tester', $loop); ``` The execution order of timers scheduled to execute at the same time is @@ -218,7 +218,7 @@ If you want to limit the number of executions, you can bind arbitrary data to a callback closure like this: ```php -function hello(LoopInterface $loop, $name) +function hello($name, LoopInterface $loop) { $n = 3; $loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) { @@ -231,7 +231,7 @@ function hello(LoopInterface $loop, $name) }); } -hello('Tester'); +hello('Tester', $loop); ``` The execution order of timers scheduled to execute at the same time is @@ -245,11 +245,12 @@ cancel a pending timer. See also [`addPeriodicTimer()`](#addperiodictimer) and [example #2](examples). You can use the [`isTimerActive()`](#istimeractive) method to check if -this timer is still "active". After a timer is successfully canceled, +this timer is still "active". After a timer is successfully cancelled, it is no longer considered "active". Calling this method on a timer instance that has not been added to this -loop instance or on a timer +loop instance or on a timer that is not "active" (or has already been +cancelled) has no effect. ### isTimerActive() @@ -258,7 +259,7 @@ check if a given timer is active. A timer is considered "active" if it has been added to this loop instance via [`addTimer()`](#addtimer) or [`addPeriodicTimer()`](#addperiodictimer) -and has not been canceled via [`cancelTimer()`](#canceltimer) and is not +and has not been cancelled via [`cancelTimer()`](#canceltimer) and is not a non-periodic timer that has already been triggered after its interval. ### futureTick() @@ -280,14 +281,14 @@ If you want to access any variables within your callback function, you can bind arbitrary data to a callback closure like this: ```php -function hello(LoopInterface $loop, $name) +function hello($name, LoopInterface $loop) { $loop->futureTick(function () use ($name) { echo "hello $name\n"; }); } -hello('Tester'); +hello('Tester', $loop); ``` Unlike timers, tick callbacks are guaranteed to be executed in the order @@ -312,8 +313,10 @@ See also [example #3](examples). ### addSignal() The `addSignal(int $signal, callable $listener): void` method can be used to -be notified about OS signals. This is useful to catch user interrupt signals or -shutdown signals from tools like `supervisor` or `systemd`. +register a listener to be notified when a signal has been caught by this process. + +This is useful to catch user interrupt signals or shutdown signals from +tools like `supervisor` or `systemd`. The listener callback function MUST be able to accept a single parameter, the signal added by this method or you MAY use a function which @@ -325,32 +328,32 @@ no effect, so for performance reasons you're recommended to not return any excessive data structures. ```php -$listener = function (int $signal) { - echo 'Caught user iterrupt signal', PHP_EOL; -}; -$loop->addSignal(SIGINT, $listener); +$loop->addSignal(SIGINT, function (int $signal) { + echo 'Caught user interrupt signal' . PHP_EOL; +}); ``` See also [example #4](examples). -**Note: A listener can only be added once to the same signal, any attempts to add it -more then once will be ignored.** +Signaling is only available on Unix-like platform, Windows isn't +supported due to operating system limitations. +This method may throw a `BadMethodCallException` if signals aren't +supported on this platform, for example when required extensions are +missing. -**Note: Signaling is only available on Unix-like platform, Windows isn't supported due -to limitations from underlying signal handlers.** +**Note: A listener can only be added once to the same signal, any +attempts to add it more then once will be ignored.** ### removeSignal() -The `removeSignal(int $signal, callable $listener): void` removes a previously added -signal listener. - -Any attempts to remove listeners that aren't registerred will be ignored. +The `removeSignal(int $signal, callable $listener): void` method can be used to +remove a previously added signal listener. ```php $loop->removeSignal(SIGINT, $listener); ``` -See also [example #4](examples). +Any attempts to remove listeners that aren't registered will be ignored. ### addReadStream() diff --git a/src/ExtEventLoop.php b/src/ExtEventLoop.php index 8eee66ad..05653c6e 100644 --- a/src/ExtEventLoop.php +++ b/src/ExtEventLoop.php @@ -42,7 +42,7 @@ function ($signal) { $this->signals->call($signal); // Ensure there are two copies of the callable around until it has been executed. // For more information see: https://bugs.php.net/bug.php?id=62452 - // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped. + // Only an issue for PHP 5, this hack can be removed once PHP 5 support has been dropped. $g = $f; $f = $g; }); diff --git a/src/LibEvLoop.php b/src/LibEvLoop.php index 638d9fa9..47701118 100644 --- a/src/LibEvLoop.php +++ b/src/LibEvLoop.php @@ -39,7 +39,7 @@ function ($signal) { $this->signals->call($signal); // Ensure there are two copies of the callable around until it has been executed. // For more information see: https://bugs.php.net/bug.php?id=62452 - // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped. + // Only an issue for PHP 5, this hack can be removed once PHP 5 support has been dropped. $g = $f; $f = $g; }, $signal); diff --git a/src/LibEventLoop.php b/src/LibEventLoop.php index 3b49e2e2..2e5a6c80 100644 --- a/src/LibEventLoop.php +++ b/src/LibEventLoop.php @@ -43,7 +43,7 @@ function ($signal) { $this->signals->call($signal); // Ensure there are two copies of the callable around until it has been executed. // For more information see: https://bugs.php.net/bug.php?id=62452 - // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped. + // Only an issue for PHP 5, this hack can be removed once PHP 5 support has been dropped. $g = $f; $f = $g; }); diff --git a/src/LoopInterface.php b/src/LoopInterface.php index c294d6e7..57783fab 100644 --- a/src/LoopInterface.php +++ b/src/LoopInterface.php @@ -152,14 +152,14 @@ public function removeWriteStream($stream); * can bind arbitrary data to a callback closure like this: * * ```php - * function hello(LoopInterface $loop, $name) + * function hello($name, LoopInterface $loop) * { * $loop->addTimer(1.0, function () use ($name) { * echo "hello $name\n"; * }); * } * - * hello('Tester'); + * hello('Tester', $loop); * ``` * * The execution order of timers scheduled to execute at the same time is @@ -205,7 +205,7 @@ public function addTimer($interval, callable $callback); * arbitrary data to a callback closure like this: * * ```php - * function hello(LoopInterface $loop, $name) + * function hello($name, LoopInterface $loop) * { * $n = 3; * $loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) { @@ -218,7 +218,7 @@ public function addTimer($interval, callable $callback); * }); * } * - * hello('Tester'); + * hello('Tester', $loop); * ``` * * The execution order of timers scheduled to execute at the same time is @@ -237,12 +237,12 @@ public function addPeriodicTimer($interval, callable $callback); * See also [`addPeriodicTimer()`](#addperiodictimer) and [example #2](examples). * * You can use the [`isTimerActive()`](#istimeractive) method to check if - * this timer is still "active". After a timer is successfully canceled, + * this timer is still "active". After a timer is successfully cancelled, * it is no longer considered "active". * * Calling this method on a timer instance that has not been added to this * loop instance or on a timer that is not "active" (or has already been - * canceled) has no effect. + * cancelled) has no effect. * * @param TimerInterface $timer The timer to cancel. * @@ -255,7 +255,7 @@ public function cancelTimer(TimerInterface $timer); * * A timer is considered "active" if it has been added to this loop instance * via [`addTimer()`](#addtimer) or [`addPeriodicTimer()`](#addperiodictimer) - * and has not been canceled via [`cancelTimer()`](#canceltimer) and is not + * and has not been cancelled via [`cancelTimer()`](#canceltimer) and is not * a non-periodic timer that has already been triggered after its interval. * * @param TimerInterface $timer The timer to check. @@ -281,14 +281,14 @@ public function isTimerActive(TimerInterface $timer); * can bind arbitrary data to a callback closure like this: * * ```php - * function hello(LoopInterface $loop, $name) + * function hello($name, LoopInterface $loop) * { * $loop->futureTick(function () use ($name) { * echo "hello $name\n"; * }); * } * - * hello('Tester'); + * hello('Tester', $loop); * ``` * * Unlike timers, tick callbacks are guaranteed to be executed in the order @@ -317,32 +317,55 @@ public function isTimerActive(TimerInterface $timer); public function futureTick(callable $listener); /** - * Registers a signal listener with the loop, which - * on it's turn registers it with a signal handler - * suitable for the loop implementation. + * Register a listener to be notified when a signal has been caught by this process. * - * A listener can only be added once, any attempts - * to add it again will be ignored. + * This is useful to catch user interrupt signals or shutdown signals from + * tools like `supervisor` or `systemd`. + * + * The listener callback function MUST be able to accept a single parameter, + * the signal added by this method or you MAY use a function which + * has no parameters at all. + * + * The listener callback function MUST NOT throw an `Exception`. + * The return value of the listener callback function will be ignored and has + * no effect, so for performance reasons you're recommended to not return + * any excessive data structures. + * + * ```php + * $loop->addSignal(SIGINT, function (int $signal) { + * echo 'Caught user interrupt signal' . PHP_EOL; + * }); + * ``` * * See also [example #4](examples). * + * Signaling is only available on Unix-like platform, Windows isn't + * supported due to operating system limitations. + * This method may throw a `BadMethodCallException` if signals aren't + * supported on this platform, for example when required extensions are + * missing. + * + * **Note: A listener can only be added once to the same signal, any + * attempts to add it more then once will be ignored.** + * * @param int $signal * @param callable $listener * - * @throws \BadMethodCallException when signals - * aren't supported by the loop, e.g. when required - * extensions are missing. + * @throws \BadMethodCallException when signals aren't supported on this + * platform, for example when required extensions are missing. * * @return void */ public function addSignal($signal, callable $listener); /** - * Removed previous registered signal listener from - * the loop, which on it's turn removes it from the - * underlying signal handler. + * Removes a previously added signal listener. * - * See also [example #4](examples). + * ```php + * $loop->removeSignal(SIGINT, $listener); + * ``` + * + * Any attempts to remove listeners that aren't registered will be ignored. * * @param int $signal * @param callable $listener diff --git a/src/StreamSelectLoop.php b/src/StreamSelectLoop.php index 4273f24e..1cf6d1a3 100644 --- a/src/StreamSelectLoop.php +++ b/src/StreamSelectLoop.php @@ -37,7 +37,7 @@ function ($signal) { $this->signals->call($signal); // Ensure there are two copies of the callable around until it has been executed. // For more information see: https://bugs.php.net/bug.php?id=62452 - // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped. + // Only an issue for PHP 5, this hack can be removed once PHP 5 support has been dropped. $g = $f; $f = $g; }); diff --git a/tests/AbstractLoopTest.php b/tests/AbstractLoopTest.php index bee7f495..6e338cc6 100644 --- a/tests/AbstractLoopTest.php +++ b/tests/AbstractLoopTest.php @@ -72,8 +72,8 @@ public function testAddReadStreamReceivesDataFromStreamReference() } /** - * Telper for above test. This happens in another helper method to verify - * the loop keep track of assigned stream resources (refcount). + * Helper for above test. This happens in another helper method to verify + * the loop keeps track of assigned stream resources (refcount). */ private function subAddReadStreamReceivesDataFromStreamReference() { pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy