NAME
Linux::Event::Reactor::Backend - Contract for readiness backends used by Linux::Event::Reactor
DESCRIPTION
This module documents the contract implemented by readiness backends for Linux::Event::Reactor.
A reactor backend owns the kernel registration and wait mechanism. The reactor engine owns watcher replacement policy, timer integration, dispatch order, signal integration, wakeups, and pidfd policy.
Backends are duck-typed, but they are expected to implement the method surface and callback semantics documented here.
REQUIRED METHODS
new(%args)
Construct the backend object.
name()
Return a short backend name such as epoll.
watch($fh, $mask, $cb, %opt)
Register readiness interest for $fh and return the integer file descriptor.
The callback ABI is:
$cb->($loop, $fh, $fd, $mask, $tag)Where $loop and $tag come from %opt if provided.
unwatch($fh_or_fd)
Remove an existing registration. Return true if a registration was removed.
run_once($loop, $timeout_s = undef)
Enter the backend wait once, dispatch native readiness callbacks, and return the number of processed events when available.
OPTIONAL METHODS
modify($fh_or_fd, $mask, %opt)
Update an existing registration without a delete-and-add cycle. The reactor can fall back to unwatch plus watch when this method is absent.
READINESS MASKS
The reactor uses these bit flags:
READABLE => 0x01
WRITABLE => 0x02
PRIO => 0x04
RDHUP => 0x08
ET => 0x10
ONESHOT => 0x20
ERR => 0x40
HUP => 0x80The backend is responsible for translating between these masks and the native kernel representation.
CALLBACK RULES
Backend callbacks may run inline from run_once. That is normal for the reactor model.
A backend must not reinterpret watcher policy. In particular, it must not change the dispatch order chosen by the reactor engine.
FILEHANDLE OWNERSHIP
A reactor backend observes filehandles. It does not take ownership of them. Closing a filehandle remains the caller's responsibility.
SEE ALSO
Linux::Event::Reactor, Linux::Event::Reactor::Backend::Epoll, Linux::Event::Proactor::Backend