Menu

Reference

Reference / Io\Poll

Context

finalclass
final class Context

A set of watched handles that can be waited on for readiness.

Create one with a {@see Backend}, register handles with {@see add}, then call {@see wait} to learn which became ready. A handle can be watched by one watcher per context.

$ctx = new Io\Poll\Context(Io\Poll\Backend::Poll);
$watcher = $ctx->add(new StreamPollHandle($stream), [Io\Poll\Event::Read]);
foreach ($ctx->wait(1) as $ready) {
    // $ready->getHandle() is readable
}

Example

use Io\Poll\Backend;
use Io\Poll\Context;
use Io\Poll\Event;

$ctx = new Context(Backend::Poll);
[$a, $b] = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM, 0);

$watcher = $ctx->add(new StreamPollHandle($a), [Event::Read], 'reader');
echo "ready before write: ", count($ctx->wait(0)), "\n";

fwrite($b, "ping");
$ready = $ctx->wait(0);
echo "ready after write: ", count($ready), "\n";
echo $ready[0]->getData(), " triggered: ", $ready[0]->getTriggeredEvents()[0]->name, "\n";
echo "payload: ", fread($a, 4), "\n";

$watcher->remove();
var_dump($watcher->isActive());

Output

ready before write: 0
ready after write: 1
reader triggered: Read
payload: ping
bool(false)

Methods

__construct()Create a context.
getBackend()The backend in use.
watchSignal()Watch for a signal instead of a file descriptor (kqueue only).
takeSignal()Whether a watched signal fired during the last {@see wait}.
add()Start watching a handle.
wait()Wait until a watched handle is ready.

__construct()#source

function __construct(private Backend $backend = Backend::Auto)

Create a context.

Parameters

$backend Backend = Backend::Auto
the mechanism to use; Backend::Auto picks epoll, kqueue or poll for the platform

Throws

BackendUnavailableException
if the backend is not available here
FailedContextInitializationException
if the kernel object cannot be created

getBackend()#source

function getBackend(): Backend

The backend in use.

Returns

Backend — the concrete backend; never Backend::Auto

watchSignal()#source

function watchSignal(int $signo): bool

Watch for a signal instead of a file descriptor (kqueue only).

The signal must be blocked for the process, as signals handled through pcntl_signal() are. When it fires, wait() returns and {@see takeSignal} answers true. Backends without this notion return false; on Linux use a signalfd descriptor as an ordinary handle.

Parameters

$signo int
signal number

Returns

bool — true if the signal is being watched, false if unsupported or registration failed

takeSignal()#source

function takeSignal(): bool

Whether a watched signal fired during the last {@see wait}. Clears the flag.

Returns

bool — true if a signal fired since the last call

add()#source

function add(Handle $handle, array $events, mixed $data = null): Watcher

Start watching a handle.

Parameters

$handle Handle
a StreamPollHandle or FdPollHandle
$events Event[]
the events to watch; must not be empty
$data mixed = null
user data returned by Watcher::getData()

Returns

Watcher — the new watcher

Throws

\TypeError
if $events is empty
HandleAlreadyWatchedException
if this context already watches the handle
InvalidHandleException
if the handle type is not supported
FailedHandleAddException
if the kernel rejects the registration

wait()#source

function wait(
    ?int $timeoutSeconds = null,
    int $timeoutMicroseconds = 0,
    ?int $maxEvents = null
): array

Wait until a watched handle is ready.

Returns the watchers whose handles became ready, with their triggered events set. null timeout waits without limit, 0 polls and returns at once. A signal interrupting the wait yields an empty array. With nothing watched the call returns an empty array immediately. $maxEvents limits the batch the kernel returns (64 by default) on the epoll and kqueue backends. The poll backend returns at most $maxEvents watchers and reports the rest on the next call, rotating the scan start so no descriptor is starved.

Parameters

$timeoutSeconds int|null = null
seconds to wait, or null to wait indefinitely
$timeoutMicroseconds int = 0
additional microseconds
$maxEvents int|null = null
maximum number of ready watchers per call

Returns

Watcher[] — the watchers whose fds became ready

Throws

FailedPollWaitException
if the system call fails

View source