Documentation

EventLoop
in package

FinalYes

Accessor to allow global access to the event loop.

Tags
see
Driver

Table of Contents

Properties

$driver  : Driver

Methods

cancel()  : void
Cancel a callback.
defer()  : string
Defer the execution of a callback.
delay()  : string
Delay the execution of a callback.
disable()  : string
Disable a callback immediately.
enable()  : string
Enable a callback to be active starting in the next tick.
getDriver()  : Driver
Retrieve the event loop driver that is in scope.
getErrorHandler()  : null|callable(Throwable): void
Gets the error handler closure or {@code null} if none is set.
getIdentifiers()  : array<string|int, string>
Returns all registered non-cancelled callback identifiers.
getSuspension()  : Suspension
Returns an object used to suspend and resume execution of the current fiber or {main}.
getType()  : CallbackType
Returns the type of the callback identified by the given callback identifier.
isEnabled()  : bool
Returns whether the callback identified by the given callback identifier is currently enabled.
isReferenced()  : bool
Returns whether the callback identified by the given callback identifier is currently referenced.
onReadable()  : string
Execute a callback when a stream resource becomes readable or is closed for reading.
onSignal()  : string
Execute a callback when a signal is received.
onWritable()  : string
Execute a callback when a stream resource becomes writable or is closed for writing.
queue()  : void
Queue a microtask.
reference()  : string
Reference a callback.
repeat()  : string
Repeatedly execute a callback.
run()  : void
Run the event loop.
setDriver()  : void
Sets the driver to be used as the event loop.
setErrorHandler()  : void
Set a callback to be executed when an error occurs.
unreference()  : string
Unreference a callback.
__construct()  : mixed
Disable construction as this is a static class.

Properties

Methods

cancel()

Cancel a callback.

public static cancel(string $callbackId) : void

This will detach the event loop from all resources that are associated to the callback. After this operation the callback is permanently invalid. Calling this function MUST NOT fail, even if passed an invalid identifier.

Parameters
$callbackId : string

The callback identifier.

defer()

Defer the execution of a callback.

public static defer(callable(string): void $closure) : string

The deferred callback MUST be executed before any other type of callback in a tick. Order of enabling MUST be preserved when executing the callbacks.

The created callback MUST immediately be marked as enabled, but only be activated (i.e. callback can be called) right before the next tick. Deferred callbacks MUST NOT be called in the tick they were enabled.

Parameters
$closure : callable(string): void

The callback to defer. The $callbackId will be invalidated before the callback invocation.

Return values
string —

A unique identifier that can be used to cancel, enable or disable the callback.

delay()

Delay the execution of a callback.

public static delay(float $delay, callable(string): void $closure) : string

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 callback MUST immediately be marked as enabled, but only be activated (i.e. callback can be called) right before the next tick. Callbacks MUST NOT be called in the tick they were enabled.

Parameters
$delay : float

The amount of time, in seconds, to delay the execution for.

$closure : callable(string): void

The callback to delay. The $callbackId will be invalidated before the callback invocation.

Return values
string —

A unique identifier that can be used to cancel, enable or disable the callback.

disable()

Disable a callback immediately.

public static disable(string $callbackId) : string

A callback MUST be disabled immediately, e.g. if a deferred callback disables another deferred callback, the second deferred callback isn't executed in this tick.

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

Parameters
$callbackId : string

The callback identifier.

Return values
string —

The callback identifier.

enable()

Enable a callback to be active starting in the next tick.

public static enable(string $callbackId) : string

Callbacks MUST immediately be marked as enabled, but only be activated (i.e. callbacks can be called) right before the next tick. Callbacks MUST NOT be called in the tick they were enabled.

Parameters
$callbackId : string

The callback identifier.

Tags
throws
InvalidCallbackError

If the callback identifier is invalid.

Return values
string —

The callback identifier.

getDriver()

Retrieve the event loop driver that is in scope.

public static getDriver() : Driver
Return values
Driver

getErrorHandler()

Gets the error handler closure or {@code null} if none is set.

public static getErrorHandler() : null|callable(Throwable): void
Return values
null|callable(Throwable): void —

The previous handler, null if there was none.

getIdentifiers()

Returns all registered non-cancelled callback identifiers.

public static getIdentifiers() : array<string|int, string>
Return values
array<string|int, string> —

Callback identifiers.

getSuspension()

Returns an object used to suspend and resume execution of the current fiber or {main}.

public static getSuspension() : Suspension

Calls from the same fiber will return the same suspension object.

Return values
Suspension

getType()

Returns the type of the callback identified by the given callback identifier.

public static getType(string $callbackId) : CallbackType
Parameters
$callbackId : string

The callback identifier.

Return values
CallbackType —

The callback type.

isEnabled()

Returns whether the callback identified by the given callback identifier is currently enabled.

public static isEnabled(string $callbackId) : bool
Parameters
$callbackId : string

The callback identifier.

Return values
bool —

true if the callback is currently enabled, otherwise false.

isReferenced()

Returns whether the callback identified by the given callback identifier is currently referenced.

public static isReferenced(string $callbackId) : bool
Parameters
$callbackId : string

The callback identifier.

Return values
bool —

true if the callback is currently referenced, otherwise false.

onReadable()

Execute a callback when a stream resource becomes readable or is closed for reading.

public static onReadable(resource $stream, callable(string, resource): void $closure) : string

Warning: Closing resources locally, e.g. with fclose, might not invoke the callback. Be sure to cancel the callback when closing the resource locally. Drivers MAY choose to notify the user if there are callbacks on invalid resources, but are not required to, due to the high performance impact. Callbacks on closed resources are therefore undefined behavior.

Multiple callbacks on the same stream MAY be executed in any order.

The created callback MUST immediately be marked as enabled, but only be activated (i.e. callback can be called) right before the next tick. Callbacks MUST NOT be called in the tick they were enabled.

Parameters
$stream : resource

The stream to monitor.

$closure : callable(string, resource): void

The callback to execute.

Return values
string —

A unique identifier that can be used to cancel, enable or disable the callback.

onSignal()

Execute a callback when a signal is received.

public static onSignal(int $signal, callable(string, int): void $closure) : string

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 callbacks on the same signal MAY be executed in any order.

The created callback MUST immediately be marked as enabled, but only be activated (i.e. callback can be called) right before the next tick. Callbacks MUST NOT be called in the tick they were enabled.

Parameters
$signal : int

The signal number to monitor.

$closure : callable(string, int): void

The callback to execute.

Tags
throws
UnsupportedFeatureException

If signal handling is not supported.

Return values
string —

A unique identifier that can be used to cancel, enable or disable the callback.

onWritable()

Execute a callback when a stream resource becomes writable or is closed for writing.

public static onWritable(resource $stream, callable(string, resource): void $closure) : string

Warning: Closing resources locally, e.g. with fclose, might not invoke the callback. Be sure to cancel the callback when closing the resource locally. Drivers MAY choose to notify the user if there are callbacks on invalid resources, but are not required to, due to the high performance impact. Callbacks on closed resources are therefore undefined behavior.

Multiple callbacks on the same stream MAY be executed in any order.

The created callback MUST immediately be marked as enabled, but only be activated (i.e. callback can be called) right before the next tick. Callbacks MUST NOT be called in the tick they were enabled.

Parameters
$stream : resource

The stream to monitor.

$closure : callable(string, resource): void

The callback to execute.

Return values
string —

A unique identifier that can be used to cancel, enable or disable the callback.

queue()

Queue a microtask.

public static queue(Closure $closure, mixed ...$args) : void

The queued callback MUST be executed immediately once the event loop gains control. Order of queueing MUST be preserved when executing the callbacks. Recursive scheduling can thus result in infinite loops, use with care.

Does NOT create an event callback, thus CAN NOT be marked as disabled or unreferenced. Use EventLoop::defer() if you need these features.

Parameters
$closure : Closure

The callback to queue.

$args : mixed

The callback arguments.

reference()

Reference a callback.

public static reference(string $callbackId) : string

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

Parameters
$callbackId : string

The callback identifier.

Tags
throws
InvalidCallbackError

If the callback identifier is invalid.

Return values
string —

The callback identifier.

repeat()

Repeatedly execute a callback.

public static repeat(float $interval, callable(string): void $closure) : string

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 callback MUST immediately be marked as enabled, but only be activated (i.e. callback can be called) right before the next tick. Callbacks MUST NOT be called in the tick they were enabled.

Parameters
$interval : float

The time interval, in seconds, to wait between executions.

$closure : callable(string): void

The callback to repeat.

Return values
string —

A unique identifier that can be used to cancel, enable or disable the callback.

run()

Run the event loop.

public static run() : void

This function may only be called from {main}, that is, not within a fiber.

Libraries should use the API instead of calling this method.

This method will not return until the event loop does not contain any pending, referenced callbacks anymore.

setDriver()

Sets the driver to be used as the event loop.

public static setDriver(Driver $driver) : void
Parameters
$driver : Driver

setErrorHandler()

Set a callback to be executed when an error occurs.

public static setErrorHandler(null|callable(Throwable): void $errorHandler) : void

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.

Parameters
$errorHandler : null|callable(Throwable): void

The callback to execute. null will clear the current handler.

unreference()

Unreference a callback.

public static unreference(string $callbackId) : string

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

Parameters
$callbackId : string

The callback identifier.

Return values
string —

The callback identifier.

__construct()

Disable construction as this is a static class.

private __construct() : mixed 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results