NAME

Linux::Event::Backend - Backend contract for Linux::Event::Loop

DESCRIPTION

This module documents the minimal backend interface expected by Linux::Event::Loop. Backends are intentionally duck-typed.

The loop owns scheduling policy (clock/timer/scheduler). The backend owns the wait/dispatch mechanism (epoll now, io_uring later).

STATUS

EXPERIMENTAL / WORK IN PROGRESS

The API is not yet considered stable and may change without notice.

REQUIRED METHODS

new(%args)

Create the backend instance.

watch($fh, $mask, $cb, %opt) -> $fd

Register a filehandle for readiness notifications.

Callback signature (standardized by this project):

$cb->($loop, $fh, $fd, $mask, $tag);

Where:

• $loop is the Linux::Event::Loop instance

• $fh is the watched filehandle

• $fd is the integer file descriptor

• $mask is an integer readiness mask (backend-defined bit layout, standardized within this project)

• $tag is an arbitrary user value (optional; may be undef)

Backends may accept additional options in %opt. This distribution uses:

• _loop - the loop reference to pass through to the callback

• tag - the tag value to pass through to the callback

unwatch($fh_or_fd) -> $bool

Remove a watcher by filehandle or file descriptor.

run_once($loop, $timeout_s=undef) -> $n

Block until events occur (or timeout) and dispatch them.

Return value is backend-defined; for now callers should not rely on it.

OPTIONAL METHODS

modify($fh_or_fd, $mask, %opt) -> $bool

Update an existing watcher registration (e.g. add/remove interest in writable). If not implemented, the loop may fall back to unwatch+watch.

SEE ALSO

Linux::Event::Loop, Linux::Event::Backend::Epoll