NAME
Linux::Event::Proactor::Backend - Contract for completion backends used by Linux::Event::Proactor
DESCRIPTION
This module documents the contract implemented by completion backends for Linux::Event::Proactor.
A proactor backend submits operations to an underlying completion mechanism, tracks backend tokens, delivers raw completions, and participates in cancellation. The proactor engine itself owns operation objects, callback queueing, result normalization, and settle-once guarantees.
REQUIRED METHODS
_new(%args)
Construct the backend. The loop argument is required.
name()
Return a short backend name such as uring or fake.
_submit_read($op, %args)
_submit_write($op, %args)
_submit_recv($op, %args)
_submit_send($op, %args)
_submit_accept($op, %args)
_submit_connect($op, %args)
_submit_timeout($op, %args)
_submit_shutdown($op, %args)
_submit_close($op, %args)
Submit the operation and return a backend token suitable for registry and cancellation bookkeeping.
_cancel_op($op)
Attempt to cancel the in-flight operation. Cancellation may complete asynchronously. The backend must cooperate with the proactor's settle-once and registry rules.
_complete_backend_events()
Drive backend completion processing once and return the number of processed backend events when available.
COMPLETION RULES
A backend must never run user callbacks inline. It should report raw completion facts back into the owning proactor so the proactor can normalize the result and queue any callback.
For io_uring-style backends, a negative completion result is a negative errno. The backend or the engine must normalize that into a positive errno and create a Linux::Event::Error object.
BUFFER LIFETIME
For operations that expose user buffers to the kernel, the backend must keep the necessary Perl values alive until the kernel no longer needs them.
CANCELLATION AND RACES
Cancellation is inherently racy. A backend must be written so that an operation cannot settle twice even when completion and cancellation race closely together.
SEE ALSO
Linux::Event::Proactor, Linux::Event::Proactor::Backend::Uring, Linux::Event::Proactor::Backend::Fake, Linux::Event::Operation, Linux::Event::Error