Amp\Loop\UvDriver class UvDriver extends Amp\Loop\Driver

Summary

Properties

Methods

Properties

Methods

__construct — public function __construct()
No documentation.
cancel — public function cancel(string $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.

Type Parameter Description Default Value
string $watcherId The watcher identifier. none
isSupported — public function isSupported(): bool
No documentation.
getHandle — public function getHandle()

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.

dispatch — protected function dispatch(bool $blocking)

Dispatches any pending read/write, timer, and signal events.

Type Parameter Description Default Value
bool $blocking No documentation. none
activate — protected function activate(array $watchers)

Activates (enables) all the given watchers.

Type Parameter Description Default Value
array $watchers No documentation. none
deactivate — protected function deactivate(Amp\Loop\Watcher $watcher)

Deactivates (disables) the given watcher.

Type Parameter Description Default Value
Amp\Loop\Watcher $watcher No documentation. none
run — public function run(): void

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.

stop — public function stop(): void

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.

defer — public function defer(callable $callback, mixed $data = null): string

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.

Type Parameter Description Default Value
callable $callback No documentation. none
mixed $data Arbitrary data given to the callback function as the `$data` parameter. null
delay — public function delay(int $delay, callable $callback, mixed $data = null): string

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.

Type Parameter Description Default Value
int $delay The amount of time, in milliseconds, to delay the execution for. none
callable $callback No documentation. none
mixed $data Arbitrary data given to the callback function as the `$data` parameter. null
repeat — public function repeat(int $interval, callable $callback, mixed $data = null): string

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.

Type Parameter Description Default Value
int $interval The time interval, in milliseconds, to wait between executions. none
callable $callback No documentation. none
mixed $data Arbitrary data given to the callback function as the `$data` parameter. null
onReadable — public function onReadable(resource $stream, callable $callback, mixed $data = null): string

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.

Type Parameter Description Default Value
resource $stream The stream to monitor. none
callable $callback No documentation. none
mixed $data Arbitrary data given to the callback function as the `$data` parameter. null
onWritable — public function onWritable(resource $stream, callable $callback, mixed $data = null): string

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.

Type Parameter Description Default Value
resource $stream The stream to monitor. none
callable $callback No documentation. none
mixed $data Arbitrary data given to the callback function as the `$data` parameter. null
onSignal — public function onSignal(int $signo, callable $callback, mixed $data = null): string

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.

Type Parameter Description Default Value
int $signo The signal number to monitor. none
callable $callback No documentation. none
mixed $data Arbitrary data given to the callback function as the $data parameter. null
enable — public function enable(string $watcherId): void

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.

Type Parameter Description Default Value
string $watcherId The watcher identifier. none
disable — public function disable(string $watcherId): void

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.

Type Parameter Description Default Value
string $watcherId The watcher identifier. none
reference — public function reference(string $watcherId): void

Reference a watcher.

This will keep the event loop alive whilst the watcher is still being monitored. Watchers have this state by default.

Type Parameter Description Default Value
string $watcherId The watcher identifier. none
unreference — public function unreference(string $watcherId): void

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.

Type Parameter Description Default Value
string $watcherId The watcher identifier. none
setState — public final function setState(string $key, mixed $value): void

Stores information in the loop bound registry.

Stored information is package private. Packages MUST NOT retrieve the stored state of other packages. Packages MUST use their namespace as prefix for keys. They may do so by using SomeClass::class as key.

If packages want to expose loop bound state to consumers other than the package, they SHOULD provide a dedicated interface for that purpose instead of sharing the storage key.

Type Parameter Description Default Value
string $key The namespaced storage key. none
mixed $value The value to be stored. none
getState — public final function getState(string $key): mixed

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 their namespace as prefix for keys. They may do so by using SomeClass::class as key.

If packages want to expose loop bound state to consumers other than the package, they SHOULD provide a dedicated interface for that purpose instead of sharing the storage key.

Type Parameter Description Default Value
string $key The namespaced storage key. none
setErrorHandler — public function setErrorHandler(callable $callback = null)
No documentation.
Type Parameter Description Default Value
callable $callback No documentation. null
error — protected function error(Throwable $exception)

Invokes the error handler with the given exception.

Type Parameter Description Default Value
Throwable $exception The exception thrown from a watcher callback. none
__debugInfo — public function __debugInfo(): array

Returns the same array of data as getInfo().

getInfo — public function getInfo(): array

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],
    "running"          => bool
];

Implementations MAY optionally add more information in the array but at minimum the above key => value format MUST always be provided.