Documentation

TracingDriver
in package
implements Driver

FinalYes

Table of Contents

Interfaces

Driver
The driver MUST run in its own fiber and execute callbacks in a separate fiber. If fibers are reused, the driver needs to call {@see FiberLocal::clear()} after running the callback.

Properties

$cancelTraces  : array<string, string>
$creationTraces  : array<string, string>
$driver  : Driver
$enabledCallbacks  : array<string, true>
$unreferencedCallbacks  : array<string, true>

Methods

__construct()  : mixed
__debugInfo()  : array<string|int, mixed>
Returns some useful information about the event loop.
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.
dump()  : string
enable()  : string
Enable a callback to be active starting in the next tick.
getErrorHandler()  : null|callable(Throwable): void
Gets the error handler closure or {@code null} if none is set.
getHandle()  : null|object|resource
Get the underlying loop handle.
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.
isRunning()  : bool
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.
setErrorHandler()  : void
Set a callback to be executed when an error occurs.
stop()  : void
Stop the event loop.
unreference()  : string
Unreference a callback.
formatStacktrace()  : string
Formats a stacktrace obtained via `debug_backtrace()`.
getCancelTrace()  : string
getCreationTrace()  : string

Properties

$cancelTraces

private array<string, string> $cancelTraces = []

$creationTraces

private array<string, string> $creationTraces = []

$enabledCallbacks

private array<string, true> $enabledCallbacks = []

$unreferencedCallbacks

private array<string, true> $unreferencedCallbacks = []

Methods

__debugInfo()

Returns some useful information about the event loop.

public __debugInfo() : array<string|int, mixed>

If this method isn't implemented, dumping the event loop in a busy application, even indirectly, is a pain.

Return values
array<string|int, mixed>

cancel()

Cancel a callback.

public 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 defer(Closure $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. Callbacks MUST NOT be called in the tick they were enabled.

Parameters
$closure : Closure

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 delay(float $delay, Closure $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 : Closure

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 disable(string $callbackId) : string

A callback MUST be disabled immediately, e.g. if a deferred callback disables a later 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 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.

Return values
string —

The callback identifier.

getErrorHandler()

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

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

The previous handler, null if there was none.

getHandle()

Get the underlying loop handle.

public getHandle() : null|object|resource
Tags
inheritdoc
Return values
null|object|resource —

The loop handle the event loop operates on. null if there is none.

getIdentifiers()

Returns all registered non-cancelled callback identifiers.

public 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 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 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 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 isReferenced(string $callbackId) : bool
Parameters
$callbackId : string

The callback identifier.

Return values
bool —

true if the callback is currently referenced, otherwise false.

isRunning()

public isRunning() : bool
Return values
bool —

True if the event loop is running, false if it is stopped.

onReadable()

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

public onReadable(mixed $stream, Closure $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 : mixed

The stream to monitor.

$closure : Closure

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 onSignal(int $signal, Closure $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 : Closure

The callback to execute.

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 onWritable(mixed $stream, Closure $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 : mixed

The stream to monitor.

$closure : Closure

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 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 reference(string $callbackId) : string

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

Parameters
$callbackId : string

The callback identifier.

Return values
string —

The callback identifier.

repeat()

Repeatedly execute a callback.

public repeat(float $interval, Closure $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 : Closure

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 run() : void

One iteration of the loop is called one "tick". A tick covers the following steps:

  1. Activate callbacks created / enabled in the last tick / before run().
  2. Execute all enabled deferred callbacks.
  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 callbacks 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.

setErrorHandler()

Set a callback to be executed when an error occurs.

public setErrorHandler(Closure|null $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 : Closure|null

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

stop()

Stop the event loop.

public stop() : void

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.

unreference()

Unreference a callback.

public 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.

formatStacktrace()

Formats a stacktrace obtained via `debug_backtrace()`.

private formatStacktrace(array<int, array{args?: list, class?: class-string, file?: string, function: string, line?: int, object?: object, type?: string}> $trace) : string
Parameters
$trace : array<int, array{args?: list, class?: class-string, file?: string, function: string, line?: int, object?: object, type?: string}>

Output of debug_backtrace().

Return values
string —

Formatted stacktrace.

getCancelTrace()

private getCancelTrace(string $callbackId) : string
Parameters
$callbackId : string
Return values
string

getCreationTrace()

private getCreationTrace(string $callbackId) : string
Parameters
$callbackId : string
Return values
string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results