Documentation and examples for deferred execution via futureTick()

Author: clue

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
 

examples/03-ticks.php

@@ -0,0 +1,15 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = React\EventLoop\Factory::create();
+
+$loop->futureTick(function () {
+    echo 'b';
+});
+$loop->futureTick(function () {
+    echo 'c';
+});
+echo 'a';
+
+$loop->run();

examples/91-benchmark-ticks.php

@@ -0,0 +1,15 @@
+<?php
+
+use React\EventLoop\Factory;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+
+$n = isset($argv[1]) ? (int)$argv[1] : 1000 * 100;
+
+for ($i = 0; $i < $n; ++$i) {
+    $loop->nextTick(function () { });
+}
+
+$loop->run();

examples/92-benchmark-timers.php

@@ -0,0 +1,15 @@
+<?php
+
+use React\EventLoop\Factory;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+
+$n = isset($argv[1]) ? (int)$argv[1] : 1000 * 100;
+
+for ($i = 0; $i < $n; ++$i) {
+    $loop->addTimer(0, function () { });
+}
+
+$loop->run();

examples/93-benchmark-ticks-delay.php

@@ -0,0 +1,22 @@
+<?php
+
+use React\EventLoop\Factory;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+
+$ticks = isset($argv[1]) ? (int)$argv[1] : 1000 * 100;
+$tick = function () use (&$tick, &$ticks, $loop) {
+    if ($ticks > 0) {
+        --$ticks;
+        //$loop->addTimer(0, $tick);
+        $loop->nextTick($tick);
+    } else {
+        echo 'done';
+    }
+};
+
+$tick();
+
+$loop->run();

examples/94-benchmark-timers-delay.php

@@ -0,0 +1,22 @@
+<?php
+
+use React\EventLoop\Factory;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$loop = Factory::create();
+
+$ticks = isset($argv[1]) ? (int)$argv[1] : 1000 * 100;
+$tick = function () use (&$tick, &$ticks, $loop) {
+    if ($ticks > 0) {
+        --$ticks;
+        //$loop->nextTick($tick);
+        $loop->addTimer(0, $tick);
+    } else {
+        echo 'done';
+    }
+};
+
+$tick();
+
+$loop->run();

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.
      */