Automatically run Loop at end of program (autorun)

Author: clue

README.md

@@ -15,6 +15,7 @@ single [`run()`](#run) call that is controlled by the user.
 * [Usage](#usage)
     * [Loop](#loop)
         * [Loop methods](#loop-methods)
+        * [Loop autorun](#loop-autorun)
         * [get()](#get)
     * [~~Factory~~](#factory)
         * [~~create()~~](#create)
@@ -76,8 +77,6 @@ Loop::addPeriodicTimer(5, function () {
     $formatted = number_format($memory, 3).'K';
     echo "Current memory usage: {$formatted}\n";
 });
-
-Loop::run();
 ```
 
 See also the [examples](examples).
@@ -98,8 +97,6 @@ Loop::addTimer(1.0, function () use ($timer) {
     Loop::cancelTimer($timer);
     echo 'Done' . PHP_EOL;
 });
-
-Loop::run();
 ```
 
 As an alternative, you can also explicitly create an event loop instance at the
@@ -127,12 +124,13 @@ In both cases, the program would perform the exact same steps.
 1. The event loop instance is created at the beginning of the program. This is
    implicitly done the first time you call the [`Loop` class](#loop) or
    explicitly when using the deprecated [`Factory::create() method`](#create)
-   (or manually instantiating any of the [loop implementation](#loop-implementations)).
+   (or manually instantiating any of the [loop implementations](#loop-implementations)).
 2. The event loop is used directly or passed as an instance to library and
    application code. In this example, a periodic timer is registered with the
    event loop which simply outputs `Tick` every fraction of a second until another
    timer stops the periodic timer after a second.
-3. The event loop is run at the end of the program with a single [`run()`](#run)
+3. The event loop is run at the end of the program. This is automatically done
+   when using [`Loop` class](#loop) or explicitly with a single [`run()`](#run)
    call at the end of the program.
 
 As of `v1.2.0`, we highly recommend using the [`Loop` class](#loop).
@@ -176,8 +174,6 @@ Loop::addTimer(1.0, function () use ($timer) {
     Loop::cancelTimer($timer);
     echo 'Done' . PHP_EOL;
 });
-
-Loop::run();
 ```
 
 On the other hand, if you're familiar with object-oriented programming (OOP) and
@@ -208,14 +204,31 @@ class Greeter
 $greeter = new Greeter(Loop::get());
 $greeter->greet('Alice');
 $greeter->greet('Bob');
-
-Loop::run();
 ```
 
 Each static method call will be forwarded as-is to the underlying event loop
 instance by using the [`Loop::get()`](#get) call internally.
 See [`LoopInterface`](#loopinterface) for more details about available methods.
 
+#### Loop autorun
+
+When using the `Loop` class, it will automatically execute the loop at the end of
+the program. This means the following example will schedule a timer and will
+automatically execute the program until the timer event fires:
+
+```php
+use React\EventLoop\Loop;
+
+Loop::addTimer(1.0, function () {
+    echo 'Hello' . PHP_EOL;
+});
+```
+
+As of `v1.2.0`, we highly recommend using the `Loop` class this way and omitting any
+explicit [`run()`](#run) calls. For BC reasons, the explicit [`run()`](#run)
+method is still valid and may still be useful in some applications, especially
+for a transition period towards the more concise style.
+
 #### get()
 
 The `get(): LoopInterface` method can be used to
@@ -262,8 +275,6 @@ class Greeter
 $greeter = new Greeter(Loop::get());
 $greeter->greet('Alice');
 $greeter->greet('Bob');
-
-Loop::run();
 ```
 
 See [`LoopInterface`](#loopinterface) for more details about available methods.

examples/01-timers.php

@@ -11,5 +11,3 @@
 Loop::addTimer(0.3, function () {
     echo 'hello ';
 });
-
-Loop::run();

examples/02-periodic.php

@@ -12,5 +12,3 @@
     Loop::cancelTimer($timer);
     echo 'Done' . PHP_EOL;
 });
-
-Loop::run();

examples/03-ticks.php

@@ -11,5 +11,3 @@
     echo 'c';
 });
 echo 'a';
-
-Loop::run();

examples/04-signals.php

@@ -15,5 +15,3 @@
 });
 
 echo 'Listening for SIGINT. Use "kill -SIGINT ' . getmypid() . '" or CTRL+C' . PHP_EOL;
-
-Loop::run();

examples/11-consume-stdin.php

@@ -24,5 +24,3 @@
 
     echo strlen($chunk) . ' bytes' . PHP_EOL;
 });
-
-Loop::run();

examples/12-generate-yes.php

@@ -37,5 +37,3 @@
         $data = substr($data, $r) . substr($data, 0, $r);
     }
 });
-
-Loop::run();

examples/13-http-client-blocking.php

@@ -29,5 +29,3 @@
 
     echo $chunk;
 });
-
-Loop::run();

examples/14-http-client-async.php

@@ -58,5 +58,3 @@
         echo $chunk;
     });
 });
-
-Loop::run();

examples/21-http-server.php

@@ -32,5 +32,3 @@
     $formatted = number_format($memory, 3).'K';
     echo "Current memory usage: {$formatted}\n";
 });
-
-Loop::run();

examples/91-benchmark-ticks.php

@@ -9,5 +9,3 @@
 for ($i = 0; $i < $n; ++$i) {
     Loop::futureTick(function () { });
 }
-
-Loop::run();

examples/92-benchmark-timers.php

@@ -9,5 +9,3 @@
 for ($i = 0; $i < $n; ++$i) {
     Loop::addTimer(0, function () { });
 }
-
-Loop::run();

examples/93-benchmark-ticks-delay.php

@@ -16,5 +16,3 @@
 };
 
 $tick();
-
-Loop::run();

examples/94-benchmark-timers-delay.php

@@ -16,5 +16,3 @@
 };
 
 $tick();
-
-Loop::run();

src/Loop.php

@@ -12,7 +12,6 @@ final class Loop
      */
     private static $instance;
 
-
     /**
      * Returns the event loop.
      * When no loop is set it will it will call the factory to create one.
@@ -31,7 +30,22 @@ public static function get()
             return self::$instance;
         }
 
-        self::$instance = Factory::create();
+        self::$instance = $loop = Factory::create();
+
+        // Automatically run loop at end of program, unless already started explicitly.
+        // This is tested using child processes, so coverage is actually 100%, see BinTest.
+        // @codeCoverageIgnoreStart
+        $hasRun = false;
+        $loop->futureTick(function () use (&$hasRun) {
+            $hasRun = true;
+        });
+
+        register_shutdown_function(function () use ($loop, &$hasRun) {
+            if (!$hasRun) {
+                $loop->run();
+            }
+        });
+        // @codeCoverageIgnoreEnd
 
         return self::$instance;
     }

tests/BinTest.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace React\Tests\EventLoop;
+
+class BinTest extends TestCase
+{
+    /**
+     * @before
+     */
+    public function setUpBin()
+    {
+        if (!defined('PHP_BINARY') || defined('HHVM_VERSION')) {
+            $this->markTestSkipped('Tests not supported on legacy PHP 5.3 or HHVM');
+        }
+
+        chdir(__DIR__ . '/bin/');
+    }
+
+    public function testExecuteExampleWithoutLoopRunRunsLoopAndExecutesTicks()
+    {
+        $output = exec(escapeshellarg(PHP_BINARY) . ' 01-ticks-loop-class.php');
+
+        $this->assertEquals('abc', $output);
+    }
+
+    public function testExecuteExampleWithExplicitLoopRunRunsLoopAndExecutesTicks()
+    {
+        $output = exec(escapeshellarg(PHP_BINARY) . ' 02-ticks-loop-instance.php');
+
+        $this->assertEquals('abc', $output);
+    }
+
+    public function testExecuteExampleWithExplicitLoopRunAndStopRunsLoopAndExecutesTicksUntilStopped()
+    {
+        $output = exec(escapeshellarg(PHP_BINARY) . ' 03-ticks-loop-stop.php');
+
+        $this->assertEquals('abc', $output);
+    }
+}

tests/bin/01-ticks-loop-class.php

@@ -0,0 +1,13 @@
+<?php
+
+use React\EventLoop\Loop;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+Loop::futureTick(function () {
+    echo 'b';
+});
+Loop::futureTick(function () {
+    echo 'c';
+});
+echo 'a';

tests/bin/02-ticks-loop-instance.php

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

tests/bin/03-ticks-loop-stop.php

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