Don't run loop automatically when explicitly calling stop()

README.md

@@ -223,6 +223,25 @@ 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.
 
+If you don't want the `Loop` to run automatically, you can either explicitly
+[`run()`](#run) or [`stop()`](#stop) it. This can be useful if you're using
+a global exception handler like this:
+
+```php
+use React\EventLoop\Loop;
+
+Loop::addTimer(10.0, function () {
+    echo 'Never happens';
+});
+
+set_exception_handler(function (Throwable $e) {
+    echo 'Error: ' . $e->getMessage() . PHP_EOL;
+    Loop::stop();
+});
+
+throw new RuntimeException('Demo');
+```
+
 #### get()
 
 The `get(): LoopInterface` method can be used to

src/Loop.php

@@ -12,6 +12,9 @@ final class Loop
      */
     private static $instance;
 
+    /** @var bool */
+    private static $stopped = false;
+
     /**
      * Returns the event loop.
      * When no loop is set it will it will call the factory to create one.
@@ -32,22 +35,23 @@ public static function get()
 
         self::$instance = $loop = Factory::create();
 
-        // Automatically run loop at end of program, unless already started explicitly.
+        // Automatically run loop at end of program, unless already started or stopped 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) {
+        $stopped =& self::$stopped;
+        register_shutdown_function(function () use ($loop, &$hasRun, &$stopped) {
             // Don't run if we're coming from a fatal error (uncaught exception).
             $error = error_get_last();
             if ((isset($error['type']) ? $error['type'] : 0) & (E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR)) {
                 return;
             }
 
-            if (!$hasRun) {
+            if (!$hasRun && !$stopped) {
                 $loop->run();
             }
         });
@@ -215,6 +219,7 @@ public static function run()
      */
     public static function stop()
     {
+        self::$stopped = true;
         self::get()->stop();
     }
 }

tests/BinTest.php

@@ -54,4 +54,22 @@ public function testExecuteExampleWithUndefinedVariableShouldNotRunLoop()
 
         $this->assertLessThan(1.0, $time);
     }
+
+    public function testExecuteExampleWithExplicitStopShouldNotRunLoop()
+    {
+        $time = microtime(true);
+        exec(escapeshellarg(PHP_BINARY) . ' 21-stop.php 2>/dev/null');
+        $time = microtime(true) - $time;
+
+        $this->assertLessThan(1.0, $time);
+    }
+
+    public function testExecuteExampleWithExplicitStopInExceptionHandlerShouldNotRunLoop()
+    {
+        $time = microtime(true);
+        exec(escapeshellarg(PHP_BINARY) . ' 22-uncaught-stop.php 2>/dev/null');
+        $time = microtime(true) - $time;
+
+        $this->assertLessThan(1.0, $time);
+    }
 }

tests/bin/21-stop.php

@@ -0,0 +1,11 @@
+<?php
+
+use React\EventLoop\Loop;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+Loop::addTimer(10.0, function () {
+    echo 'never';
+});
+
+Loop::stop();

tests/bin/22-stop-uncaught.php

@@ -0,0 +1,16 @@
+<?php
+
+use React\EventLoop\Loop;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+Loop::addTimer(10.0, function () {
+    echo 'never';
+});
+
+set_exception_handler(function (Exception $e) {
+    echo 'Uncaught error occured' . PHP_EOL;
+    Loop::stop();
+});
+
+throw new RuntimeException();