danog/amp
1
0
Fork 0
mirror of https://github.com/danog/amp.git synced 2024-12-04 10:28:01 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #103 from async-interop/docs-formatting

Browse Source 
Documentation formatting
This commit is contained in:
Bob Weinand 2016-09-29 10:32:24 +02:00 committed by GitHub
commit 98106455a1
2 changed files with 86 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
src/Loop.php
View File

@ -32,11 +32,11 @@ final class Loop
/** /**
* Set the factory to be used to create a default drivers. * 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 * Setting a factory is only allowed as long as no loop is currently running. Passing null will reset the
* driver and remove the factory. * 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 * The factory will be invoked if none is passed to `Loop::execute`. A default driver will be created to
* synchronous waits in traditional applications. * support synchronous waits in traditional applications.
* *
* @param DriverFactory|null $factory New factory to replace the previous one. * @param DriverFactory|null $factory New factory to replace the previous one.
*/ */
@ -56,9 +56,11 @@ final class Loop
* Execute a callback within the scope of an event loop driver. * Execute a callback within the scope of an event loop driver.
* *
* @param callable $callback The callback to execute. * @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. * @param Driver $driver The event loop driver. If `null`, a new one is created from the set factory.
* *
* @return void * @return void
*
* @see \Interop\Async\Loop::setFactory()
*/ */
public static function execute(callable $callback, Driver $driver = null) public static function execute(callable $callback, Driver $driver = null)
{ {
@ -79,19 +81,19 @@ final class Loop
/** /**
* Create a new driver if a factory is present, otherwise throw. * Create a new driver if a factory is present, otherwise throw.
* *
* @throws \LogicException If no factory is set or no driver returned from factory. * @throws \Exception If no factory is set or no driver returned from factory.
*/ */
private static function createDriver() private static function createDriver()
{ {
if (self::$factory === null) { if (self::$factory === null) {
throw new \LogicException("No loop driver factory set; Either pass a driver to Loop::execute or set a factory."); throw new \Exception("No loop driver factory set; Either pass a driver to Loop::execute or set a factory.");
} }
$driver = self::$factory->create(); $driver = self::$factory->create();
if (!$driver instanceof Driver) { if (!$driver instanceof Driver) {
$type = is_object($driver) ? "an instance of " . get_class($driver) : gettype($driver); $type = is_object($driver) ? "an instance of " . get_class($driver) : gettype($driver);
throw new \LogicException("Loop driver factory returned {$type}, but must return an instance of Driver."); throw new \Exception("Loop driver factory returned {$type}, but must return an instance of Driver.");
} }
return $driver; return $driver;
@ -126,7 +128,7 @@ final class Loop
* Defer the execution of a callback. * Defer the execution of a callback.
* *
* @param callable(string $watcherId, mixed $data) $callback The callback to defer. * @param callable(string $watcherId, mixed $data) $callback The callback to defer.
* @param mixed $data Arbitrary data given to the callback function as the $data parameter. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
* *
* @return string An identifier that can be used to cancel, enable or disable the watcher. * @return string An identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -143,7 +145,7 @@ final class Loop
* *
* @param int $time The amount of time, in milliseconds, to delay the execution for. * @param int $time The amount of time, in milliseconds, to delay the execution for.
* @param callable(string $watcherId, mixed $data) $callback The callback to delay. * @param callable(string $watcherId, mixed $data) $callback The callback to delay.
* @param mixed $data Arbitrary data given to the callback function as the $data parameter. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
* *
* @return string An identifier that can be used to cancel, enable or disable the watcher. * @return string An identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -161,7 +163,7 @@ final class Loop
* *
* @param int $interval The time interval, in milliseconds, to wait between executions. * @param int $interval The time interval, in milliseconds, to wait between executions.
* @param callable(string $watcherId, mixed $data) $callback The callback to repeat. * @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. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
* *
* @return string An identifier that can be used to cancel, enable or disable the watcher. * @return string An identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -176,7 +178,7 @@ final class Loop
* *
* @param resource $stream The stream to monitor. * @param resource $stream The stream to monitor.
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. * @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. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
* *
* @return string An identifier that can be used to cancel, enable or disable the watcher. * @return string An identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -191,7 +193,7 @@ final class Loop
* *
* @param resource $stream The stream to monitor. * @param resource $stream The stream to monitor.
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. * @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. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
* *
* @return string An identifier that can be used to cancel, enable or disable the watcher. * @return string An identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -209,7 +211,7 @@ final class Loop
* *
* @param int $signo The signal number to monitor. * @param int $signo The signal number to monitor.
* @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute. * @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. * @param mixed $data Arbitrary data given to the callback function as the `$data` parameter.
* *
* @return string An identifier that can be used to cancel, enable or disable the watcher. * @return string An identifier that can be used to cancel, enable or disable the watcher.
* *
@ -250,8 +252,10 @@ final class Loop
} }
/** /**
* Cancel a watcher. This will detatch the event loop from all resources that are associated to the watcher. After * Cancel a watcher.
* this operation the watcher is permanently invalid. *
* This will detatch the event loop from all resources that are associated to the watcher. After this
* operation the watcher is permanently invalid.
* *
* @param string $watcherId The watcher identifier. * @param string $watcherId The watcher identifier.
* *
@ -266,8 +270,8 @@ final class Loop
/** /**
* Reference a watcher. * Reference a watcher.
* *
* This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state by * This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state
* default. * by default.
* *
* @param string $watcherId The watcher identifier. * @param string $watcherId The watcher identifier.
* *
@ -284,8 +288,8 @@ final class Loop
/** /**
* Unreference a watcher. * Unreference a watcher.
* *
* The event loop should exit the run method when only unreferenced watchers are still being monitored. Watchers * The event loop should exit the run method when only unreferenced watchers are still being monitored.
* are all referenced by default. * Watchers are all referenced by default.
* *
* @param string $watcherId The watcher identifier. * @param string $watcherId The watcher identifier.
* *
@ -300,13 +304,14 @@ final class Loop
} }
/** /**
* Stores information in the loop bound registry. This can be used to store loop bound information. Stored * Stores information in the loop bound registry.
* information is package private. Packages MUST NOT retrieve the stored state of other packages.
* *
* Therefore packages SHOULD use the following prefix to keys: `vendor.package.` * 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 to keys:
* `vendor.package.`
* *
* @param string $key namespaced storage key * @param string $key The namespaced storage key.
* @param mixed $value the value to be stored * @param mixed $value The value to be stored.
* *
* @return void * @return void
*/ */
@ -317,12 +322,12 @@ final class Loop
} }
/** /**
* Gets information stored bound to the loop. Stored information is package private. Packages MUST NOT retrieve the * Gets information stored bound to the loop.
* stored state of other packages.
* *
* Therefore packages SHOULD use the following prefix to keys: `vendor.package.` * Stored information is package private. Packages MUST NOT retrieve the stored state of other packages.
* Packages MUST use the following prefix to keys: `vendor.package.`
* *
* @param string $key namespaced storage key * @param string $key The namespaced storage key.
* *
* @return mixed previously stored value or null if it doesn't exist * @return mixed previously stored value or null if it doesn't exist
*/ */
@ -363,7 +368,7 @@ final class Loop
* "watchers" => ["referenced" => int, "unreferenced" => int], * "watchers" => ["referenced" => int, "unreferenced" => int],
* ]; * ];
* *
* Implementations MAY optionally add more information in the array but at minimum the above key => value format * Implementations MAY optionally add more information in the array but at minimum the above `key => value` format
* MUST always be provided. * MUST always be provided.
* *
* @return array * @return array

60
src/Loop/Driver.php
View File

@ -39,9 +39,9 @@ abstract class Driver
* The deferred callable MUST be executed in the next tick of the event loop and before any other type of watcher. * The deferred callable MUST be executed in the next tick of the event loop and before any other type of watcher.
* Order of enabling MUST be preserved when executing the callbacks. * Order of enabling MUST be preserved when executing the callbacks.
* *
* @param callable(string $watcherId, mixed $data) $callback The callback to defer. The $watcherId will be * @param callable(string $watcherId, mixed $data) $callback The callback to defer. The `$watcherId` will be
* invalidated before the callback call. * invalidated before the callback call.
* @param mixed $data Arbitrary data given to the callback function as the $data parameter. * @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. * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -51,12 +51,12 @@ abstract class Driver
* Delay the execution of a callback. * 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 * 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. * timers expire first, but timers with the same expiration time MAY be executed in any order.
* *
* @param int $delay The amount of time, in milliseconds, to delay the execution for. * @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 * @param callable(string $watcherId, mixed $data) $callback The callback to delay. The `$watcherId` will be
* invalidated before the callback call. * invalidated before the callback call.
* @param mixed $data Arbitrary data given to the callback function as the $data parameter. * @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. * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -71,7 +71,7 @@ abstract class Driver
* *
* @param int $interval The time interval, in milliseconds, to wait between executions. * @param int $interval The time interval, in milliseconds, to wait between executions.
* @param callable(string $watcherId, mixed $data) $callback The callback to repeat. * @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. * @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. * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -84,7 +84,7 @@ abstract class Driver
* *
* @param resource $stream The stream to monitor. * @param resource $stream The stream to monitor.
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. * @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. * @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. * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -97,7 +97,7 @@ abstract class Driver
* *
* @param resource $stream The stream to monitor. * @param resource $stream The stream to monitor.
* @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute. * @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. * @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. * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
*/ */
@ -108,7 +108,7 @@ abstract class Driver
* *
* Multiple watchers on the same signal may be executed in any order. * Multiple watchers on the same signal may be executed in any order.
* *
* NOTE: Installing a same signal on different instances of this interface is deemed undefined behavior. * NOTE: 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 * 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. * limitations of the signals being registered globally per process.
* *
@ -126,7 +126,8 @@ abstract class Driver
* Enable a watcher. * Enable a watcher.
* *
* Watchers (enabling or new watchers) MUST immediately be marked as enabled, but only be activated (i.e. callbacks * Watchers (enabling 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. * 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. * @param string $watcherId The watcher identifier.
* *
@ -137,8 +138,10 @@ abstract class Driver
abstract public function enable($watcherId); abstract public function enable($watcherId);
/** /**
* Disable a watcher. Disabling a watcher MUST NOT invalidate the watcher. Calling this function MUST NOT fail, * Disable a watcher.
* even if passed an invalid watcher. *
* 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. * @param string $watcherId The watcher identifier.
* *
@ -147,9 +150,10 @@ abstract class Driver
abstract public function disable($watcherId); abstract public function disable($watcherId);
/** /**
* Cancel a watcher. This will detatch the event loop from all resources that are associated to the watcher. After * Cancel a watcher.
* this operation the watcher is permanently invalid. Calling this function MUST NOT fail, even if passed an *
* invalid 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. * @param string $watcherId The watcher identifier.
* *
@ -186,10 +190,10 @@ abstract class Driver
abstract public function unreference($watcherId); abstract public function unreference($watcherId);
/** /**
* Stores information in the loop bound registry. This can be used to store loop bound information. Stored * Stores information in the loop bound registry.
* information is package private. Packages MUST NOT retrieve the stored state of other packages.
* *
* Therefore packages SHOULD use the following prefix to keys: `vendor.package.` * 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 string $key The namespaced storage key.
* @param mixed $value The value to be stored. * @param mixed $value The value to be stored.
@ -206,14 +210,14 @@ abstract class Driver
} }
/** /**
* Gets information stored bound to the loop. Stored information is package private. Packages MUST NOT retrieve the * Gets information stored bound to the loop.
* stored state of other packages.
* *
* Therefore packages SHOULD use the following prefix to keys: `vendor.package.` * 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 string $key The namespaced storage key.
* *
* @return mixed The previously stored value or null if it doesn't exist. * @return mixed The previously stored value or `null` if it doesn't exist.
*/ */
final public function getState($key) final public function getState($key)
{ {
@ -225,8 +229,8 @@ abstract class Driver
* *
* Subsequent calls to this method will overwrite the previous handler. * 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 * @param callable(\Throwable|\Exception $error)|null $callback The callback to execute. `null` will clear the
* handler. * current handler.
* *
* @return void * @return void
*/ */
@ -247,7 +251,7 @@ abstract class Driver
* "watchers" => ["referenced" => int, "unreferenced" => int], * "watchers" => ["referenced" => int, "unreferenced" => int],
* ]; * ];
* *
* Implementations MAY optionally add more information in the array but at minimum the above key => value format * Implementations MAY optionally add more information in the array but at minimum the above `key => value` format
* MUST always be provided. * MUST always be provided.
* *
* @return array * @return array
@ -257,12 +261,12 @@ abstract class Driver
/** /**
* Get the underlying loop handle. * Get the underlying loop handle.
* *
* Example: the uv_loop resource for libuv or the EvLoop object for libev or null for a native driver. * 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 * NOTE: This function is *not* exposed in the `Loop` class. Users shall access it directly on the respective loop
* instance. * instance.
* *
* @return null|object|resource The loop handle the event loop operates on. Null if there is none. * @return null|object|resource The loop handle the event loop operates on. `null` if there is none.
*/ */
abstract public function getHandle(); abstract public function getHandle();
} }