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() {