Add support for signal handling

README.md

@@ -292,6 +292,49 @@ echo 'a'
 
 See also [example #3](examples).
 
+### addSignal()
+
+The `addSignal(int $signal, callable $listener): void` method can be used to
+be notified about OS signals. This is useful to catch user interrupt signals or 
+shutdown signals from tools like `supervisor` or `systemd`.
+
+The listener callback function MUST be able to accept a single parameter,
+the signal added by this method or you MAY use a function which
+has no parameters at all.
+
+The listener callback function MUST NOT throw an `Exception`.
+The return value of the listener callback function will be ignored and has
+no effect, so for performance reasons you're recommended to not return
+any excessive data structures.
+
+```php
+$listener = function (int $signal){
+ echo 'Caught user iterrupt signal', PHP_EOL;
+};
+$loop->addSignal(SIGINT, $listener);
+```
+
+See also [example #4](examples).
+
+**Note: A listener can only be added once to the same signal, any attempts to add it 
+more then once will be ignored.**
+
+**Note: Signaling is only available on Unix-like platform, Windows isn't supported due 
+to limitations from underlying signal handlers.**
+
+### removeSignal()
+
+The `removeSignal(int $signal, callable $listener): void` removes a previously added 
+signal listener.
+
+Any attempts to remove listeners that aren't registerred will be ignored.
+
+```php
+$loop->removeSignal(SIGINT, $listener);
+```
+
+See also [example #4](examples).
+
 ### addReadStream()
 
 > Advanced! Note that this low-level API is considered advanced usage.

composer.json

@@ -12,7 +12,8 @@
  "suggest":{
  "ext-libevent": ">=0.1.0 for LibEventLoop and PHP5 only",
  "ext-event": "~1.0 for ExtEventLoop",
- "ext-libev": "for LibEvLoop"
+ "ext-libev": "for LibEvLoop",
+ "ext-pcntl": "For signals support when using the stream_select loop"
  },
  "autoload":{
  "psr-4":{

examples/04-signals.php

@@ -0,0 +1,12 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php'
+
+$loop = React\EventLoop\Factory::create();
+
+$loop->addSignal(SIGINT, $func = function ($signal) use ($loop, &$func){
+ echo 'Signal: ', (string)$signal, PHP_EOL;
+ $loop->removeSignal(SIGINT, $func);
+});
+
+$loop->run();

src/ExtEventLoop.php

@@ -25,13 +25,36 @@ class ExtEventLoop implements LoopInterface
  private $readListeners = [];
  private $writeListeners = [];
  private $running;
+ private $signals;
+ private $signalEvents = [];
 
  public function __construct(EventBaseConfig $config = null)
 {
  $this->eventBase = new EventBase($config);
  $this->futureTickQueue = new FutureTickQueue();
  $this->timerEvents = new SplObjectStorage();
 
+ $this->signals = new SignalsHandler(
+ $this,
+ function ($signal){
+ $this->signalEvents[$signal] = Event::signal($this->eventBase, $signal, $f = function () use ($signal, &$f){
+ $this->signals->call($signal);
+ // Ensure there are two copies of the callable around until it has been executed.
+ // For more information see: https://bugs.php.net/bug.php?id=62452
+ // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped.
+ $g = $f;
+ $f = $g;
+ });
+ $this->signalEvents[$signal]->add();
+ },
+ function ($signal){
+ if ($this->signals->count($signal) === 0){
+ $this->signalEvents[$signal]->del();
+ unset($this->signalEvents[$signal]);
+ }
+ }
+ );
+
  $this->createTimerCallback();
  $this->createStreamCallback();
  }
@@ -158,6 +181,22 @@ public function futureTick(callable $listener)
  $this->futureTickQueue->add($listener);
  }
 
+ /**
+ *{@inheritdoc}
+ */
+ public function addSignal($signal, callable $listener)
+{
+ $this->signals->add($signal, $listener);
+ }
+
+ /**
+ *{@inheritdoc}
+ */
+ public function removeSignal($signal, callable $listener)
+{
+ $this->signals->remove($signal, $listener);
+ }
+
  /**
  *{@inheritdoc}
  */

src/LibEvLoop.php

@@ -4,6 +4,7 @@
 
 use libev\EventLoop;
 use libev\IOEvent;
+use libev\SignalEvent;
 use libev\TimerEvent;
 use React\EventLoop\Tick\FutureTickQueue;
 use React\EventLoop\Timer\Timer;
@@ -22,12 +23,35 @@ class LibEvLoop implements LoopInterface
  private $readEvents = [];
  private $writeEvents = [];
  private $running;
+ private $signals;
+ private $signalEvents = [];
 
  public function __construct()
 {
  $this->loop = new EventLoop();
  $this->futureTickQueue = new FutureTickQueue();
  $this->timerEvents = new SplObjectStorage();
+
+ $this->signals = new SignalsHandler(
+ $this,
+ function ($signal){
+ $this->signalEvents[$signal] = new SignalEvent($f = function () use ($signal, &$f){
+ $this->signals->call($signal);
+ // Ensure there are two copies of the callable around until it has been executed.
+ // For more information see: https://bugs.php.net/bug.php?id=62452
+ // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped.
+ $g = $f;
+ $f = $g;
+ }, $signal);
+ $this->loop->add($this->signalEvents[$signal]);
+ },
+ function ($signal){
+ if ($this->signals->count($signal) === 0){
+ $this->loop->remove($this->signalEvents[$signal]);
+ unset($this->signalEvents[$signal]);
+ }
+ }
+ );
  }
 
  /**
@@ -170,6 +194,22 @@ public function futureTick(callable $listener)
  $this->futureTickQueue->add($listener);
  }
 
+ /**
+ *{@inheritdoc}
+ */
+ public function addSignal($signal, callable $listener)
+{
+ $this->signals->add($signal, $listener);
+ }
+
+ /**
+ *{@inheritdoc}
+ */
+ public function removeSignal($signal, callable $listener)
+{
+ $this->signals->remove($signal, $listener);
+ }
+
  /**
  *{@inheritdoc}
  */

src/LibEventLoop.php

@@ -4,6 +4,7 @@
 
 use Event;
 use EventBase;
+use React\EventLoop\Signal\Pcntl;
 use React\EventLoop\Tick\FutureTickQueue;
 use React\EventLoop\Timer\Timer;
 use React\EventLoop\Timer\TimerInterface;
@@ -26,13 +27,39 @@ class LibEventLoop implements LoopInterface
  private $readListeners = [];
  private $writeListeners = [];
  private $running;
+ private $signals;
+ private $signalEvents = [];
 
  public function __construct()
 {
  $this->eventBase = event_base_new();
  $this->futureTickQueue = new FutureTickQueue();
  $this->timerEvents = new SplObjectStorage();
 
+ $this->signals = new SignalsHandler(
+ $this,
+ function ($signal){
+ $this->signalEvents[$signal] = event_new();
+ event_set($this->signalEvents[$signal], $signal, EV_PERSIST | EV_SIGNAL, $f = function () use ($signal, &$f){
+ $this->signals->call($signal);
+ // Ensure there are two copies of the callable around until it has been executed.
+ // For more information see: https://bugs.php.net/bug.php?id=62452
+ // Only an issue for PHP 5, this hack can be removed once PHP 5 suppose has been dropped.
+ $g = $f;
+ $f = $g;
+ });
+ event_base_set($this->signalEvents[$signal], $this->eventBase);
+ event_add($this->signalEvents[$signal]);
+ },
+ function ($signal){
+ if ($this->signals->count($signal) === 0){
+ event_del($this->signalEvents[$signal]);
+ event_free($this->signalEvents[$signal]);
+ unset($this->signalEvents[$signal]);
+ }
+ }
+ );
+
  $this->createTimerCallback();
  $this->createStreamCallback();
  }
@@ -166,6 +193,22 @@ public function futureTick(callable $listener)
  $this->futureTickQueue->add($listener);
  }
 
+ /**
+ *{@inheritdoc}
+ */
+ public function addSignal($signal, callable $listener)
+{
+ $this->signals->add($signal, $listener);
+ }
+
+ /**
+ *{@inheritdoc}
+ */
+ public function removeSignal($signal, callable $listener)
+{
+ $this->signals->remove($signal, $listener);
+ }
+
  /**
  *{@inheritdoc}
  */

src/LoopInterface.php

@@ -326,6 +326,41 @@ public function isTimerActive(TimerInterface $timer);
  */
  public function futureTick(callable $listener);
 
+ /**
+ * Registers a signal listener with the loop, which
+ * on it's turn registers it with a signal handler
+ * suitable for the loop implementation.
+ *
+ * A listener can only be added once, any attempts
+ * to add it again will be ignored.
+ *
+ * See also [example #4](examples).
+ *
+ * @param int $signal
+ * @param callable $listener
+ *
+ * @throws \BadMethodCallException when signals
+ * aren't supported by the loop, e.g. when required
+ * extensions are missing.
+ *
+ * @return void
+ */
+ public function addSignal($signal, callable $listener);
+
+ /**
+ * Removed previous registered signal listener from
+ * the loop, which on it's turn removes it from the
+ * underlying signal handler.
+ *
+ * See also [example #4](examples).
+ *
+ * @param int $signal
+ * @param callable $listener
+ *
+ * @return void
+ */
+ public function removeSignal($signal, callable $listener);
+
  /**
  * Run the event loop until there are no more tasks to perform.
  */