Merge pull request #103 from clue-labs/ticks

Tick callback receives no arguments, fix cyclic dependency

Author: WyriHaximus

README.md

@@ -251,12 +251,33 @@ 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.
+The tick callback function MUST be able to accept zero parameters.
+
+The tick callback function MUST NOT throw an `Exception`.
+The return value of the tick callback function will be ignored and has
+no effect, so for performance reasons you're recommended to not return
+any excessive data structures.
+
+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)
+{
+    $loop->futureTick(function () use ($name) {
+        echo "hello $name\n";
+    });
+}
+
+hello('Tester');
+```
+
+Unlike timers, tick 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).
+This is often used to break down bigger tasks into smaller steps (a form
+of cooperative multitasking).
 
 ```php
 $loop->futureTick(function () {

examples/91-benchmark-ticks.php

@@ -9,7 +9,7 @@
 $n = isset($argv[1]) ? (int)$argv[1] : 1000 * 100;
 
 for ($i = 0; $i < $n; ++$i) {
-    $loop->nextTick(function () { });
+    $loop->futureTick(function () { });
 }
 
 $loop->run();

examples/93-benchmark-ticks-delay.php

@@ -11,7 +11,7 @@
     if ($ticks > 0) {
         --$ticks;
         //$loop->addTimer(0, $tick);
-        $loop->nextTick($tick);
+        $loop->futureTick($tick);
     } else {
         echo 'done';
     }

examples/94-benchmark-timers-delay.php

@@ -10,7 +10,7 @@
 $tick = function () use (&$tick, &$ticks, $loop) {
     if ($ticks > 0) {
         --$ticks;
-        //$loop->nextTick($tick);
+        //$loop->futureTick($tick);
         $loop->addTimer(0, $tick);
     } else {
         echo 'done';

src/ExtEventLoop.php

@@ -29,7 +29,7 @@ class ExtEventLoop implements LoopInterface
     public function __construct(EventBaseConfig $config = null)
     {
         $this->eventBase = new EventBase($config);
-        $this->futureTickQueue = new FutureTickQueue($this);
+        $this->futureTickQueue = new FutureTickQueue();
         $this->timerEvents = new SplObjectStorage();
 
         $this->createTimerCallback();

src/LibEvLoop.php

@@ -26,7 +26,7 @@ class LibEvLoop implements LoopInterface
     public function __construct()
     {
         $this->loop = new EventLoop();
-        $this->futureTickQueue = new FutureTickQueue($this);
+        $this->futureTickQueue = new FutureTickQueue();
         $this->timerEvents = new SplObjectStorage();
     }
 

src/LibEventLoop.php

@@ -30,7 +30,7 @@ class LibEventLoop implements LoopInterface
     public function __construct()
     {
         $this->eventBase = event_base_new();
-        $this->futureTickQueue = new FutureTickQueue($this);
+        $this->futureTickQueue = new FutureTickQueue();
         $this->timerEvents = new SplObjectStorage();
 
         $this->createTimerCallback();

src/LoopInterface.php

@@ -193,14 +193,49 @@ public function isTimerActive(TimerInterface $timer);
      * 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.
+     * The tick callback function MUST be able to accept zero parameters.
+     *
+     * The tick callback function MUST NOT throw an `Exception`.
+     * The return value of the tick callback function will be ignored and has
+     * no effect, so for performance reasons you're recommended to not return
+     * any excessive data structures.
+     *
+     * 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)
+     * {
+     *     $loop->futureTick(function () use ($name) {
+     *         echo "hello $name\n";
+     *     });
+     * }
+     *
+     * hello('Tester');
+     * ```
+     *
+     * Unlike timers, tick 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).
+     * 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).
      *
      * @param callable $listener The callback to invoke.
+     *
+     * @return void
      */
     public function futureTick(callable $listener);
 

src/StreamSelectLoop.php

@@ -24,7 +24,7 @@ class StreamSelectLoop implements LoopInterface
 
     public function __construct()
     {
-        $this->futureTickQueue = new FutureTickQueue($this);
+        $this->futureTickQueue = new FutureTickQueue();
         $this->timers = new Timers();
     }
 

src/Tick/FutureTickQueue.php

@@ -2,20 +2,22 @@
 
 namespace React\EventLoop\Tick;
 
-use React\EventLoop\LoopInterface;
 use SplQueue;
 
-class FutureTickQueue
+/**
+ * A tick queue implementation that can hold multiple callback functions
+ *
+ * This class should only be used internally, see LoopInterface instead.
+ *
+ * @see LoopInterface
+ * @internal
+ */
+final class FutureTickQueue
 {
-    private $eventLoop;
     private $queue;
 
-    /**
-     * @param LoopInterface $eventLoop The event loop passed as the first parameter to callbacks.
-     */
-    public function __construct(LoopInterface $eventLoop)
+    public function __construct()
     {
-        $this->eventLoop = $eventLoop;
         $this->queue = new SplQueue();
     }
 
@@ -41,8 +43,7 @@ public function tick()
 
         while ($count--) {
             call_user_func(
-                $this->queue->dequeue(),
-                $this->eventLoop
+                $this->queue->dequeue()
             );
         }
     }