danog/amp
1
0
Fork 0
mirror of https://github.com/danog/amp.git synced 2025-01-22 05:11:42 +01:00
Code Issues Projects Releases Wiki Activity

Merge async-interop/event-loop repository into amphp/amp

Browse Source
This commit is contained in:
Niklas Keller 2017-03-10 18:07:13 +01:00
commit 942cf801bd
10 changed files with 986 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
LICENSE
View File

@ -2,6 +2,7 @@
The MIT License (MIT)
Copyright (c) 2016 amphp
Copyright (c) 2016 PHP Asynchronous Interoperability Group
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal

12
phpunit.xml Normal file
View File

@ -0,0 +1,12 @@
<phpunit bootstrap="./vendor/autoload.php" colors="true">
<testsuites>
<testsuite name="Tests">
<directory>./test</directory>
</testsuite>
</testsuites>
<filter>
<whitelist addUncoveredFilesFromWhitelist="true">
<directory>./src</directory>
</whitelist>
</filter>
</phpunit>

452
src/Loop.php Normal file
View File

@ -0,0 +1,452 @@
<?php
namespace AsyncInterop;
use AsyncInterop\Loop\Driver;
use AsyncInterop\Loop\DriverFactory;
use AsyncInterop\Loop\InvalidWatcherException;
use AsyncInterop\Loop\UnsupportedFeatureException;
/**
* Accessor to allow global access to the event loop.
*
* @see \AsyncInterop\Loop\Driver
*/
final class Loop
{
/**
* @var DriverFactory
*/
private static $factory = null;
/**
* @var Driver
*/
private static $driver = null;
/**
* @var int
*/
private static $level = 0;
/**
* Set the factory to be used to create a default drivers.
*
* Setting a factory is only allowed as long as no loop is currently running. Passing null will reset the
* default driver and remove the factory.
*
* The factory will be invoked if none is passed to `Loop::execute`. A default driver will be created to
* support synchronous waits in traditional applications.
*
* @param DriverFactory|null $factory New factory to replace the previous one.
*/
public static function setFactory(DriverFactory $factory = null)
{
if (self::$level > 0) {
throw new \RuntimeException("Setting a new factory while running isn't allowed!");
}
self::$factory = $factory;
// reset it here, it will be actually instantiated inside execute() or get()
self::$driver = null;
}
/**
* Execute a callback within the scope of an event loop driver.
*
* The loop MUST continue to run until it is either stopped explicitly, no referenced watchers exist anymore, or an
* exception is thrown that cannot be handled. Exceptions that cannot be handled are exceptions thrown from an
* error handler or exceptions that would be passed to an error handler but none exists to handle them.
*
* @param callable $callback The callback to execute.
* @param Driver $driver The event loop driver. If `null`, a new one is created from the set factory.
*
* @return void
*
* @see \AsyncInterop\Loop::setFactory()
*/
public static function execute(callable $callback, Driver $driver = null)
{
$previousDriver = self::$driver;
self::$driver = $driver ?: self::createDriver();
self::$level++;
try {
self::$driver->defer($callback);
self::$driver->run();
} finally {
self::$driver = $previousDriver;
self::$level--;
}
}
/**
* Create a new driver if a factory is present, otherwise throw.
*
* @return Driver
*
* @throws \Exception If no factory is set or no driver returned from factory.
*/
private static function createDriver()
{
if (self::$factory === null) {
throw new \Exception("No loop driver factory set; Either pass a driver to Loop::execute or set a factory.");
}
$driver = self::$factory->create();
if (!$driver instanceof Driver) {
$type = is_object($driver) ? "an instance of " . get_class($driver) : gettype($driver);
throw new \Exception("Loop driver factory returned {$type}, but must return an instance of Driver.");
}
return $driver;
}
/**
* Retrieve the event loop driver that is in scope.
*
* @return Driver
*/
public static function get()
{
if (self::$driver) {
return self::$driver;
}
return self::$driver = self::createDriver();
}
/**
* Stop the event loop.
*
* When an event loop is stopped, it continues with its current tick and exits the loop afterwards. Multiple calls
* to stop MUST be ignored and MUST NOT raise an exception.
*
* @return void
*/
public static function stop()
{
$driver = self::$driver ?: self::get();
$driver->stop();
}
/**
* Defer the execution of a callback.
*
* The deferred callable MUST be executed before any other type of watcher in a tick. Order of enabling MUST be
* preserved when executing the callbacks.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param callable(string $watcherId, mixed $data) $callback The callback to defer. The `$watcherId` will be
* invalidated before the callback call.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
public static function defer(callable $callback, $data = null)
{
$driver = self::$driver ?: self::get();
return $driver->defer($callback, $data);
}
/**
* Delay the execution of a callback.
*
* The delay is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be determined by which
* timers expire first, but timers with the same expiration time MAY be executed in any order.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param int $delay The amount of time, in milliseconds, to delay the execution for.
* @param callable(string $watcherId, mixed $data) $callback The callback to delay. The `$watcherId` will be
* invalidated before the callback call.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
public static function delay($time, callable $callback, $data = null)
{
$driver = self::$driver ?: self::get();
return $driver->delay($time, $callback, $data);
}
/**
* Repeatedly execute a callback.
*
* The interval between executions is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be
* determined by which timers expire first, but timers with the same expiration time MAY be executed in any order.
* The first execution is scheduled after the first interval period.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param int $interval The time interval, in milliseconds, to wait between executions.
* @param callable(string $watcherId, mixed $data) $callback The callback to repeat.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
public static function repeat($interval, callable $callback, $data = null)
{
$driver = self::$driver ?: self::get();
return $driver->repeat($interval, $callback, $data);
}
/**
* Execute a callback when a stream resource becomes readable or is closed for reading.
*
* Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the
* watcher when closing the resource locally. Drivers MAY choose to notify the user if there are watchers on invalid
* resources, but are not required to, due to the high performance impact. Watchers on closed resources are
* therefore undefined behavior.
*
* Multiple watchers on the same stream MAY be executed in any order.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param resource $stream The stream to monitor.
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
public static function onReadable($stream, callable $callback, $data = null)
{
$driver = self::$driver ?: self::get();
return $driver->onReadable($stream, $callback, $data);
}
/**
* Execute a callback when a stream resource becomes writable or is closed for writing.
*
* Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the
* watcher when closing the resource locally. Drivers MAY choose to notify the user if there are watchers on invalid
* resources, but are not required to, due to the high performance impact. Watchers on closed resources are
* therefore undefined behavior.
*
* Multiple watchers on the same stream MAY be executed in any order.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param resource $stream The stream to monitor.
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
public static function onWritable($stream, callable $callback, $data = null)
{
$driver = self::$driver ?: self::get();
return $driver->onWritable($stream, $callback, $data);
}
/**
* Execute a callback when a signal is received.
*
* Warning: Installing the same signal on different instances of this interface is deemed undefined behavior.
* Implementations MAY try to detect this, if possible, but are not required to. This is due to technical
* limitations of the signals being registered globally per process.
*
* Multiple watchers on the same signal MAY be executed in any order.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param int $signo The signal number to monitor.
* @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*
* @throws UnsupportedFeatureException If signal handling is not supported.
*/
public static function onSignal($signo, callable $callback, $data = null)
{
$driver = self::$driver ?: self::get();
return $driver->onSignal($signo, $callback, $data);
}
/**
* Enable a watcher to be active starting in the next tick.
*
* Watchers MUST immediately be marked as enabled, but only be activated (i.e. callbacks can be called) right before
* the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*
* @throws InvalidWatcherException If the watcher identifier is invalid.
*/
public static function enable($watcherId)
{
$driver = self::$driver ?: self::get();
$driver->enable($watcherId);
}
/**
* Disable a watcher immediately.
*
* A watcher MUST be disabled immediately, e.g. if a defer watcher disables a later defer watcher, the second defer
* watcher isn't executed in this tick.
*
* Disabling a watcher MUST NOT invalidate the watcher. Calling this function MUST NOT fail, even if passed an
* invalid watcher.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*/
public static function disable($watcherId)
{
$driver = self::$driver ?: self::get();
$driver->disable($watcherId);
}
/**
* Cancel a watcher.
*
* This will detatch the event loop from all resources that are associated to the watcher. After this operation the
* watcher is permanently invalid. Calling this function MUST NOT fail, even if passed an invalid watcher.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*/
public static function cancel($watcherId)
{
$driver = self::$driver ?: self::get();
$driver->cancel($watcherId);
}
/**
* Reference a watcher.
*
* This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state by
* default.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*
* @throws InvalidWatcherException If the watcher identifier is invalid.
*/
public static function reference($watcherId)
{
$driver = self::$driver ?: self::get();
$driver->reference($watcherId);
}
/**
* Unreference a watcher.
*
* The event loop should exit the run method when only unreferenced watchers are still being monitored. Watchers
* are all referenced by default.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*
* @throws InvalidWatcherException If the watcher identifier is invalid.
*/
public static function unreference($watcherId)
{
$driver = self::$driver ?: self::get();
$driver->unreference($watcherId);
}
/**
* Stores information in the loop bound registry.
*
* This can be used to store loop bound information. Stored information is package private. Packages MUST NOT
* retrieve the stored state of other packages. Packages MUST use the following prefix for keys: `vendor.package.`
*
* @param string $key The namespaced storage key.
* @param mixed $value The value to be stored.
*
* @return void
*/
public static function setState($key, $value)
{
$driver = self::$driver ?: self::get();
$driver->setState($key, $value);
}
/**
* Gets information stored bound to the loop.
*
* Stored information is package private. Packages MUST NOT retrieve the stored state of other packages. Packages
* MUST use the following prefix for keys: `vendor.package.`
*
* @param string $key The namespaced storage key.
*
* @return mixed The previously stored value or `null` if it doesn't exist.
*/
public static function getState($key)
{
$driver = self::$driver ?: self::get();
return $driver->getState($key);
}
/**
* Set a callback to be executed when an error occurs.
*
* The callback receives the error as the first and only parameter. The return value of the callback gets ignored.
* If it can't handle the error, it MUST throw the error. Errors thrown by the callback or during its invocation
* MUST be thrown into the `run` loop and stop the driver.
*
* Subsequent calls to this method will overwrite the previous handler.
*
* @param callable(\Throwable|\Exception $error)|null $callback The callback to execute. `null` will clear the
* current handler.
*
* @return callable(\Throwable|\Exception $error)|null The previous handler, `null` if there was none.
*/
public static function setErrorHandler(callable $callback = null)
{
$driver = self::$driver ?: self::get();
return $driver->setErrorHandler($callback);
}
/**
* Retrieve an associative array of information about the event loop driver.
*
* The returned array MUST contain the following data describing the driver's currently registered watchers:
*
* [
* "defer" => ["enabled" => int, "disabled" => int],
* "delay" => ["enabled" => int, "disabled" => int],
* "repeat" => ["enabled" => int, "disabled" => int],
* "on_readable" => ["enabled" => int, "disabled" => int],
* "on_writable" => ["enabled" => int, "disabled" => int],
* "on_signal" => ["enabled" => int, "disabled" => int],
* "enabled_watchers" => ["referenced" => int, "unreferenced" => int],
* ];
*
* Implementations MAY optionally add more information in the array but at minimum the above `key => value` format
* MUST always be provided.
*
* @return array Statistics about the loop in the described format.
*/
public static function getInfo()
{
$driver = self::$driver ?: self::get();
return $driver->getInfo();
}
/**
* Disable construction as this is a static class.
*/
private function __construct()
{
// intentionally left blank
}
}

317
src/Loop/Driver.php Normal file
View File

@ -0,0 +1,317 @@
<?php
namespace AsyncInterop\Loop;
/**
* Event loop driver which implements all basic operations to allow interoperability.
*
* Watchers (enabled or new watchers) MUST immediately be marked as enabled, but only be activated (i.e. callbacks can
* be called) right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* All registered callbacks MUST NOT be called from a file with strict types enabled (`declare(strict_types=1)`).
*/
abstract class Driver
{
/**
* @var array
*/
private $registry = [];
/**
* Run the event loop.
*
* One iteration of the loop is called one "tick". A tick covers the following steps:
*
* 1. Activate watchers created / enabled in the last tick / before `run()`.
* 2. Execute all enabled defer watchers.
* 3. Execute all due timer, pending signal and actionable stream callbacks, each only once per tick.
*
* The loop MUST continue to run until it is either stopped explicitly, no referenced watchers exist anymore, or an
* exception is thrown that cannot be handled. Exceptions that cannot be handled are exceptions thrown from an
* error handler or exceptions that would be passed to an error handler but none exists to handle them.
*
* @return void
*/
abstract public function run();
/**
* Stop the event loop.
*
* When an event loop is stopped, it continues with its current tick and exits the loop afterwards. Multiple calls
* to stop MUST be ignored and MUST NOT raise an exception.
*
* @return void
*/
abstract public function stop();
/**
* Defer the execution of a callback.
*
* The deferred callable MUST be executed before any other type of watcher in a tick. Order of enabling MUST be
* preserved when executing the callbacks.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param callable(string $watcherId, mixed $data) $callback The callback to defer. The `$watcherId` will be
* invalidated before the callback call.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
abstract public function defer(callable $callback, $data = null);
/**
* Delay the execution of a callback.
*
* The delay is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be determined by which
* timers expire first, but timers with the same expiration time MAY be executed in any order.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param int $delay The amount of time, in milliseconds, to delay the execution for.
* @param callable(string $watcherId, mixed $data) $callback The callback to delay. The `$watcherId` will be
* invalidated before the callback call.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
abstract public function delay($delay, callable $callback, $data = null);
/**
* Repeatedly execute a callback.
*
* The interval between executions is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be
* determined by which timers expire first, but timers with the same expiration time MAY be executed in any order.
* The first execution is scheduled after the first interval period.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param int $interval The time interval, in milliseconds, to wait between executions.
* @param callable(string $watcherId, mixed $data) $callback The callback to repeat.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
abstract public function repeat($interval, callable $callback, $data = null);
/**
* Execute a callback when a stream resource becomes readable or is closed for reading.
*
* Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the
* watcher when closing the resource locally. Drivers MAY choose to notify the user if there are watchers on invalid
* resources, but are not required to, due to the high performance impact. Watchers on closed resources are
* therefore undefined behavior.
*
* Multiple watchers on the same stream MAY be executed in any order.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param resource $stream The stream to monitor.
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
abstract public function onReadable($stream, callable $callback, $data = null);
/**
* Execute a callback when a stream resource becomes writable or is closed for writing.
*
* Warning: Closing resources locally, e.g. with `fclose`, might not invoke the callback. Be sure to `cancel` the
* watcher when closing the resource locally. Drivers MAY choose to notify the user if there are watchers on invalid
* resources, but are not required to, due to the high performance impact. Watchers on closed resources are
* therefore undefined behavior.
*
* Multiple watchers on the same stream MAY be executed in any order.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param resource $stream The stream to monitor.
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute.
* @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/
abstract public function onWritable($stream, callable $callback, $data = null);
/**
* Execute a callback when a signal is received.
*
* Warning: Installing the same signal on different instances of this interface is deemed undefined behavior.
* Implementations MAY try to detect this, if possible, but are not required to. This is due to technical
* limitations of the signals being registered globally per process.
*
* Multiple watchers on the same signal MAY be executed in any order.
*
* The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
* right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param int $signo The signal number to monitor.
* @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.
* @param mixed $data Arbitrary data given to the callback function as the $data parameter.
*
* @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*
* @throws UnsupportedFeatureException If signal handling is not supported.
*/
abstract public function onSignal($signo, callable $callback, $data = null);
/**
* Enable a watcher to be active starting in the next tick.
*
* Watchers MUST immediately be marked as enabled, but only be activated (i.e. callbacks can be called) right before
* the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*
* @throws InvalidWatcherException If the watcher identifier is invalid.
*/
abstract public function enable($watcherId);
/**
* Disable a watcher immediately.
*
* A watcher MUST be disabled immediately, e.g. if a defer watcher disables a later defer watcher, the second defer
* watcher isn't executed in this tick.
*
* Disabling a watcher MUST NOT invalidate the watcher. Calling this function MUST NOT fail, even if passed an
* invalid watcher.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*/
abstract public function disable($watcherId);
/**
* Cancel a watcher.
*
* This will detatch the event loop from all resources that are associated to the watcher. After this operation the
* watcher is permanently invalid. Calling this function MUST NOT fail, even if passed an invalid watcher.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*/
abstract public function cancel($watcherId);
/**
* Reference a watcher.
*
* This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state by
* default.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*
* @throws InvalidWatcherException If the watcher identifier is invalid.
*/
abstract public function reference($watcherId);
/**
* Unreference a watcher.
*
* The event loop should exit the run method when only unreferenced watchers are still being monitored. Watchers
* are all referenced by default.
*
* @param string $watcherId The watcher identifier.
*
* @return void
*
* @throws InvalidWatcherException If the watcher identifier is invalid.
*/
abstract public function unreference($watcherId);
/**
* Stores information in the loop bound registry.
*
* This can be used to store loop bound information. Stored information is package private. Packages MUST NOT
* retrieve the stored state of other packages. Packages MUST use the following prefix for keys: `vendor.package.`
*
* @param string $key The namespaced storage key.
* @param mixed $value The value to be stored.
*
* @return void
*/
final public function setState($key, $value)
{
if ($value === null) {
unset($this->registry[$key]);
} else {
$this->registry[$key] = $value;
}
}
/**
* Gets information stored bound to the loop.
*
* Stored information is package private. Packages MUST NOT retrieve the stored state of other packages. Packages
* MUST use the following prefix for keys: `vendor.package.`
*
* @param string $key The namespaced storage key.
*
* @return mixed The previously stored value or `null` if it doesn't exist.
*/
final public function getState($key)
{
return isset($this->registry[$key]) ? $this->registry[$key] : null;
}
/**
* Set a callback to be executed when an error occurs.
*
* The callback receives the error as the first and only parameter. The return value of the callback gets ignored.
* If it can't handle the error, it MUST throw the error. Errors thrown by the callback or during its invocation
* MUST be thrown into the `run` loop and stop the driver.
*
* Subsequent calls to this method will overwrite the previous handler.
*
* @param callable(\Throwable|\Exception $error)|null $callback The callback to execute. `null` will clear the
* current handler.
*
* @return callable(\Throwable|\Exception $error)|null The previous handler, `null` if there was none.
*/
abstract public function setErrorHandler(callable $callback = null);
/**
* Retrieve an associative array of information about the event loop driver.
*
* The returned array MUST contain the following data describing the driver's currently registered watchers:
*
* [
* "defer" => ["enabled" => int, "disabled" => int],
* "delay" => ["enabled" => int, "disabled" => int],
* "repeat" => ["enabled" => int, "disabled" => int],
* "on_readable" => ["enabled" => int, "disabled" => int],
* "on_writable" => ["enabled" => int, "disabled" => int],
* "on_signal" => ["enabled" => int, "disabled" => int],
* "enabled_watchers" => ["referenced" => int, "unreferenced" => int],
* ];
*
* Implementations MAY optionally add more information in the array but at minimum the above `key => value` format
* MUST always be provided.
*
* @return array Statistics about the loop in the described format.
*/
abstract public function getInfo();
/**
* Get the underlying loop handle.
*
* Example: the `uv_loop` resource for `libuv` or the `EvLoop` object for `libev` or `null` for a native driver.
*
* Note: This function is *not* exposed in the `Loop` class. Users shall access it directly on the respective loop
* instance.
*
* @return null|object|resource The loop handle the event loop operates on. `null` if there is none.
*/
abstract public function getHandle();
}

18
src/Loop/DriverFactory.php Normal file
View File

@ -0,0 +1,18 @@
<?php
namespace AsyncInterop\Loop;
/**
* Allows creating new driver instances.
*
* @see \AsyncInterop\Loop::setFactory()
*/
interface DriverFactory
{
/**
* Create a new event loop driver instance.
*
* @return Driver
*/
public function create();
}

37
src/Loop/InvalidWatcherException.php Normal file
View File

@ -0,0 +1,37 @@
<?php
namespace AsyncInterop\Loop;
/**
* MUST be thrown if any operation (except disable() and cancel()) is attempted with an invalid watcher identifier.
*
* An invalid watcher identifier is any identifier that is not yet emitted by the driver or cancelled by the user.
*/
class InvalidWatcherException extends \Exception
{
/** @var string */
private $watcherId;
/**
* @param string $watcherId The watcher identifier.
* @param string|null $message The exception message.
*/
public function __construct($watcherId, $message = null)
{
$this->watcherId = $watcherId;
if ($message === null) {
$message = "An invalid watcher identifier has been used: '{$watcherId}'";
}
parent::__construct($message);
}
/**
* @return string The watcher identifier.
*/
public function getWatcherId()
{
return $this->watcherId;
}
}

13
src/Loop/UnsupportedFeatureException.php Normal file
View File

@ -0,0 +1,13 @@
<?php
namespace AsyncInterop\Loop;
/**
* MUST be thrown if a feature is not supported by the system.
*
* This might happen if ext-pcntl is missing and the loop driver doesn't support another way to dispatch signals.
*/
class UnsupportedFeatureException extends \Exception
{
}

48
test/DummyDriver.php Normal file
View File

@ -0,0 +1,48 @@
<?php
namespace AsyncInterop\Loop\Test;
use AsyncInterop\Loop\Driver;
class DummyDriver extends Driver
{
public $defers;
public $handler;
public static $id = "a";
public function run() {
while (list($defer, $data) = array_shift($this->defers)) {
try {
$defer(self::$id++, $data);
} catch (\Exception $e) {
if ($handler = $this->handler) {
$handler($e);
} else {
throw $e;
}
}
}
}
public function defer(callable $callback, $data = null) {
$this->defers[] = [$callback, $data];
}
public function setErrorHandler(callable $callback = null) {
$this->handler = $callback;
}
public function stop() {}
public function delay($delay, callable $callback, $data = null) { return self::$id++; }
public function repeat($interval, callable $callback, $data = null) { return self::$id++; }
public function onReadable($stream, callable $callback, $data = null) { return self::$id++; }
public function onWritable($stream, callable $callback, $data = null) { return self::$id++; }
public function onSignal($signo, callable $callback, $data = null) { return self::$id++; }
public function enable($watcherId) {}
public function disable($watcherId) {}
public function cancel($watcherId) {}
public function reference($watcherId) {}
public function unreference($watcherId) {}
public function getInfo() {}
public function getHandle() {}
}

42
test/LoopStateTest.php Normal file
View File

@ -0,0 +1,42 @@
<?php
namespace AsyncInterop\Loop;
class LoopStateTest extends \PHPUnit_Framework_TestCase
{
private $loop;
protected function setUp()
{
$this->loop = $this->getMockForAbstractClass(Driver::class);
}
/** @test */
public function defaultsToNull()
{
$this->assertNull($this->loop->getState("foobar"));
}
/**
* @test
* @dataProvider provideValues
*/
public function getsPreviouslySetValue($value)
{
$this->loop->setState("foobar", $value);
$this->assertSame($value, $this->loop->getState("foobar"));
}
public function provideValues()
{
return [
["string"],
[42],
[1.001],
[true],
[false],
[null],
[new \StdClass],
];
}
}

46
test/LoopTest.php Normal file
View File

@ -0,0 +1,46 @@
<?php
namespace AsyncInterop\Loop\Test;
use AsyncInterop\Loop;
class LoopTest extends \PHPUnit_Framework_TestCase
{
protected function setUp() {
Loop::setFactory(null);
}
/**
* @test
* @expectedException \RuntimeException
* @expectedExceptionMessage new factory while running isn't allowed
*/
public function setFactoryFailsIfRunning() {
$driver = new DummyDriver;
$factory = $this->getMockBuilder(Loop\DriverFactory::class)->getMock();
$factory->method("create")->willReturn($driver);
Loop::setFactory($factory);
Loop::execute(function () use ($factory) {
Loop::setFactory($factory);
});
}
/** @test */
public function executeStackReturnsScopedDriver() {
$driver1 = new DummyDriver;
$driver2 = new DummyDriver;
Loop::execute(function () use ($driver1, $driver2) {
$this->assertSame($driver1, Loop::get());
Loop::execute(function () use ($driver2) {
$this->assertSame($driver2, Loop::get());
}, $driver2);
$this->assertSame($driver1, Loop::get());
}, $driver1);
}
}