diff --git a/README.md b/README.md index 4e4ee3d0..d46414ca 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,34 @@ All of the loops support these features: * File descriptor polling * One-off timers * Periodic timers -* Deferred execution of callbacks +* Deferred execution on future loop tick + +### futureTick() + +The `futureTick(callable $listener): void` method can be used to +schedule a callback to be invoked on a future tick of the event loop. + +This works very much similar to timers with an interval of zero seconds, +but does not require the overhead of scheduling a timer queue. + +Unlike timers, callbacks are guaranteed to be executed in the order they +are enqueued. +Also, once a callback is enqueued, there's no way to cancel this operation. + +This is often used to break down bigger tasks into smaller steps (a form of +cooperative multitasking). + +```php +$loop->futureTick(function () { + echo 'b'; +}); +$loop->futureTick(function () { + echo 'c'; +}); +echo 'a'; +``` + +See also [example #3](examples). ## Install diff --git a/examples/03-ticks.php b/examples/03-ticks.php new file mode 100644 index 00000000..3f36c6d4 --- /dev/null +++ b/examples/03-ticks.php @@ -0,0 +1,15 @@ +futureTick(function () { + echo 'b'; +}); +$loop->futureTick(function () { + echo 'c'; +}); +echo 'a'; + +$loop->run(); diff --git a/examples/91-benchmark-ticks.php b/examples/91-benchmark-ticks.php new file mode 100644 index 00000000..cdaa1e15 --- /dev/null +++ b/examples/91-benchmark-ticks.php @@ -0,0 +1,15 @@ +nextTick(function () { }); +} + +$loop->run(); diff --git a/examples/92-benchmark-timers.php b/examples/92-benchmark-timers.php new file mode 100644 index 00000000..e2e02e49 --- /dev/null +++ b/examples/92-benchmark-timers.php @@ -0,0 +1,15 @@ +addTimer(0, function () { }); +} + +$loop->run(); diff --git a/examples/93-benchmark-ticks-delay.php b/examples/93-benchmark-ticks-delay.php new file mode 100644 index 00000000..e242c65f --- /dev/null +++ b/examples/93-benchmark-ticks-delay.php @@ -0,0 +1,22 @@ + 0) { + --$ticks; + //$loop->addTimer(0, $tick); + $loop->nextTick($tick); + } else { + echo 'done'; + } +}; + +$tick(); + +$loop->run(); diff --git a/examples/94-benchmark-timers-delay.php b/examples/94-benchmark-timers-delay.php new file mode 100644 index 00000000..69084e37 --- /dev/null +++ b/examples/94-benchmark-timers-delay.php @@ -0,0 +1,22 @@ + 0) { + --$ticks; + //$loop->nextTick($tick); + $loop->addTimer(0, $tick); + } else { + echo 'done'; + } +}; + +$tick(); + +$loop->run(); diff --git a/src/LoopInterface.php b/src/LoopInterface.php index b4750dd0..c2e5f75c 100644 --- a/src/LoopInterface.php +++ b/src/LoopInterface.php @@ -88,7 +88,15 @@ public function isTimerActive(TimerInterface $timer); /** * Schedule a callback to be invoked on a future tick of the event loop. * - * Callbacks are guaranteed to be executed in the order they are enqueued. + * This works very much similar to timers with an interval of zero seconds, + * but does not require the overhead of scheduling a timer queue. + * + * Unlike timers, callbacks are guaranteed to be executed in the order they + * are enqueued. + * Also, once a callback is enqueued, there's no way to cancel this operation. + * + * This is often used to break down bigger tasks into smaller steps (a form of + * cooperative multitasking). * * @param callable $listener The callback to invoke. */