Merge pull request #103 from clue-labs/ticks

WyriHaximus · web-flow · commit eaaed7c5c4ca · 2017-04-28T21:05:20.000+02:00
Tick callback receives no arguments, fix cyclic dependency
diff --git a/README.md b/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 () {
diff --git a/examples/91-benchmark-ticks.php b/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();
diff --git a/examples/93-benchmark-ticks-delay.php b/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';
     }
diff --git a/examples/94-benchmark-timers-delay.php b/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';
diff --git a/src/ExtEventLoop.php b/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();
diff --git a/src/LibEvLoop.php b/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();
     }
 
diff --git a/src/LibEventLoop.php b/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();
diff --git a/src/LoopInterface.php b/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);
 
diff --git a/src/StreamSelectLoop.php b/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();
     }
 
diff --git a/src/Tick/FutureTickQueue.php b/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()
             );
         }
     }
diff --git a/tests/AbstractLoopTest.php b/tests/AbstractLoopTest.php
@@ -296,8 +296,7 @@ public function testFutureTick()
     {
         $called = false;
 
-        $callback = function ($loop) use (&$called) {
-            $this->assertSame($this->loop, $loop);
+        $callback = function () use (&$called) {
             $called = true;
         };
 

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@`
`9`	`9`	`$n = isset($argv[1]) ? (int)$argv[1] : 1000 * 100;`
`10`	`10`
`11`	`11`	`for ($i = 0; $i < $n; ++$i) {`
`12`		`- $loop->nextTick(function () { });`
	`12`	`+ $loop->futureTick(function () { });`
`13`	`13`	`}`
`14`	`14`
`15`	`15`	`$loop->run();`
Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@`
`11`	`11`	`if ($ticks > 0) {`
`12`	`12`	`--$ticks;`
`13`	`13`	`//$loop->addTimer(0, $tick);`
`14`		`- $loop->nextTick($tick);`
	`14`	`+ $loop->futureTick($tick);`
`15`	`15`	`} else {`
`16`	`16`	`echo 'done';`
`17`	`17`	`}`
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ class ExtEventLoop implements LoopInterface`
`29`	`29`	`public function __construct(EventBaseConfig $config = null)`
`30`	`30`	`{`
`31`	`31`	`$this->eventBase = new EventBase($config);`
`32`		`- $this->futureTickQueue = new FutureTickQueue($this);`
	`32`	`+ $this->futureTickQueue = new FutureTickQueue();`
`33`	`33`	`$this->timerEvents = new SplObjectStorage();`
`34`	`34`
`35`	`35`	`$this->createTimerCallback();`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ class LibEvLoop implements LoopInterface`
`26`	`26`	`public function __construct()`
`27`	`27`	`{`
`28`	`28`	`$this->loop = new EventLoop();`
`29`		`- $this->futureTickQueue = new FutureTickQueue($this);`
	`29`	`+ $this->futureTickQueue = new FutureTickQueue();`
`30`	`30`	`$this->timerEvents = new SplObjectStorage();`
`31`	`31`	`}`
`32`	`32`
Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ class LibEventLoop implements LoopInterface`
`30`	`30`	`public function __construct()`
`31`	`31`	`{`
`32`	`32`	`$this->eventBase = event_base_new();`
`33`		`- $this->futureTickQueue = new FutureTickQueue($this);`
	`33`	`+ $this->futureTickQueue = new FutureTickQueue();`
`34`	`34`	`$this->timerEvents = new SplObjectStorage();`
`35`	`35`
`36`	`36`	`$this->createTimerCallback();`
Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ class StreamSelectLoop implements LoopInterface`
`24`	`24`
`25`	`25`	`public function __construct()`
`26`	`26`	`{`
`27`		`- $this->futureTickQueue = new FutureTickQueue($this);`
	`27`	`+ $this->futureTickQueue = new FutureTickQueue();`
`28`	`28`	`$this->timers = new Timers();`
`29`	`29`	`}`
`30`	`30`