PHP Class Interop\Async\Loop\Driver

Show file Open project: async-interop/event-loop Class Usage Examples

Public Methods

Method	Description
cancel ( string $watcherId ) : void	Cancel a watcher.
defer ( callable $callback, mixed $data = null ) : string	Defer the execution of a callback.
delay ( integer $delay, callable $callback, mixed $data = null ) : string	Delay the execution of a callback.
disable ( string $watcherId ) : void	Disable a watcher.
enable ( string $watcherId ) : void	Enable a watcher.
getHandle ( ) : null \| object \| resource	Get the underlying loop handle.
getState ( string $key ) : mixed	Gets information stored bound to the loop.
info ( ) : array	Retrieve an associative array of information about the event loop driver.
onReadable ( resource $stream, callable $callback, mixed $data = null ) : string	Execute a callback when a stream resource becomes readable or is closed for reading.
onSignal ( integer $signo, callable $callback, mixed $data = null ) : string	Execute a callback when a signal is received.
onWritable ( resource $stream, callable $callback, mixed $data = null ) : string	Execute a callback when a stream resource becomes writable or is closed for writing.
reference ( string $watcherId ) : void	Reference a watcher.
repeat ( integer $interval, callable $callback, mixed $data = null ) : string	Repeatedly execute a callback.
run ( ) : void	Start the event loop.
setErrorHandler ( callable $callback = null ) : void	Set a callback to be executed when an error occurs.
setState ( string $key, mixed $value ) : void	Stores information in the loop bound registry.
stop ( ) : void	Stop the event loop.
unreference ( string $watcherId ) : void	Unreference a watcher.

Method Details

cancel() abstract public method

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.

abstract public cancel ( string $watcherId ) : void
$watcherId	string	The watcher identifier.
return	void

defer() abstract public method

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.

abstract public defer ( callable $callback, mixed $data = null ) : string
$callback	callable
$data	mixed	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.

delay() abstract public method

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.

abstract public delay ( integer $delay, callable $callback, mixed $data = null ) : string
$delay	integer	The amount of time, in milliseconds, to delay the execution for.
$callback	callable
$data	mixed	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.

disable() abstract public method

Disabling a watcher MUST NOT invalidate the watcher. Calling this function MUST NOT fail, even if passed an invalid watcher.

abstract public disable ( string $watcherId ) : void
$watcherId	string	The watcher identifier.
return	void

enable() abstract public method

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.

abstract public enable ( string $watcherId ) : void
$watcherId	string	The watcher identifier.
return	void

getHandle() abstract public method

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.

abstract public getHandle ( ) : null \| object \| resource
return	null \| object \| resource	The loop handle the event loop operates on. `null` if there is none.

getState() final public method

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.

final public getState ( string $key ) : mixed
$key	string	The namespaced storage key.
return	mixed	The previously stored value or `null` if it doesn't exist.

info() abstract public method

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], "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.

abstract public info ( ) : array
return	array

onReadable() abstract public method

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.

abstract public onReadable ( resource $stream, callable $callback, mixed $data = null ) : string
$stream	resource	The stream to monitor.
$callback	callable
$data	mixed	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.

onSignal() abstract public method

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.

abstract public onSignal ( integer $signo, callable $callback, mixed $data = null ) : string
$signo	integer	The signal number to monitor.
$callback	callable
$data	mixed	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.

onWritable() abstract public method

abstract public onWritable ( resource $stream, callable $callback, mixed $data = null ) : string
$stream	resource	The stream to monitor.
$callback	callable
$data	mixed	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.

reference() abstract public method

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

abstract public reference ( string $watcherId ) : void
$watcherId	string	The watcher identifier.
return	void

repeat() abstract public method

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.

abstract public repeat ( integer $interval, callable $callback, mixed $data = null ) : string
$interval	integer	The time interval, in milliseconds, to wait between executions.
$callback	callable
$data	mixed	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.

run() abstract public method

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.

abstract public run ( ) : void
return	void

setErrorHandler() abstract public method

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.

abstract public setErrorHandler ( callable $callback = null ) : void
$callback	callable
return	void

setState() final public method

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.

final public setState ( string $key, mixed $value ) : void
$key	string	The namespaced storage key.
$value	mixed	The value to be stored.
return	void

stop() abstract public method

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.

abstract public stop ( ) : void
return	void

unreference() abstract public method

The event loop should exit the run method when only unreferenced watchers are still being monitored. Watchers are all referenced by default.

abstract public unreference ( string $watcherId ) : void
$watcherId	string	The watcher identifier.
return	void