/ 
Linux-Event-0.003_001
/ Linux::Event::Loop

NAME

Linux::Event::Loop - Backend-agnostic Linux event loop (timers + epoll watchers)

SYNOPSIS

use v5.36;
use Linux::Event;

my $loop = Linux::Event->new;

# I/O watcher (read/write) with user data stored on the watcher:
my $conn = My::Conn->new(...);

my $w = $loop->watch($fh,
  read  => \&My::Conn::on_read,
  write => \&My::Conn::on_write,
  error => \&My::Conn::on_error,   # optional
  data  => $conn,                   # optional (avoid closure captures)

  edge_triggered => 0,              # optional, default false
  oneshot        => 0,              # optional, default false
);

$w->disable_write; # enable later when output buffered

# Timers (seconds, float ok)
$loop->after(0.250, sub ($loop) {
  warn "250ms elapsed\n";
});

$loop->run;

DESCRIPTION

Linux::Event::Loop ties together:

The loop owns policy (timer scheduling and dispatch ordering). The backend owns readiness waiting and low-level polling.

WATCHERS

watch($fh, %spec) -> Linux::Event::Watcher

Create a mutable watcher for a filehandle. Interest is inferred from installed handlers and enable/disable state.

Supported keys in %spec:

  • read - coderef (optional)

  • write - coderef (optional)

  • error - coderef (optional). Called on EPOLLERR (see Dispatch).

  • data - user data (optional). Stored on the watcher to avoid closure captures.

  • edge_triggered - boolean (optional, advanced). Defaults to false.

  • oneshot - boolean (optional, advanced). Defaults to false.

Handlers are invoked as:

read  => sub ($loop, $fh, $watcher) { ... }
write => sub ($loop, $fh, $watcher) { ... }
error => sub ($loop, $fh, $watcher) { ... }

The watcher can be modified later using its methods (enable/disable write, swap handlers, cancel, etc).

Dispatch contract

When the backend reports events for a file descriptor, the loop dispatches as:

  • If EPOLLERR is present and an error handler is installed and enabled, call error first and return.

  • Otherwise EPOLLERR behaves like both readable and writable readiness (read+write may be invoked).

  • EPOLLHUP also triggers read readiness (EOF detection via read() returning 0).

  • read is invoked before write when both are ready.

The loop does not auto-close filehandles and does not auto-cancel watchers; user code decides lifecycle (cancel then close is recommended).

LISTENING SOCKETS

listen(%spec) -> $socket =head2 listen(%spec) -> ($socket, $watcher)

Create a nonblocking listening socket and register it with the loop. This is a convenience wrapper around raw socket/bind/listen plus a watcher that drains accept() in a bounded loop.

The listener uses the normal watcher key read as the "accept callback". Each accepted client socket is passed as $fh to that callback.

Required keys:

  • type - one of tcp4, tcp6, unix

  • read - coderef, invoked for each accepted client socket

Common keys:

  • host - for tcp4/tcp6 (defaults: 0.0.0.0 / ::)

  • port - for tcp4/tcp6 (required)

  • path - for unix (required)

  • unlink - for unix (optional). If true, unlink path before bind.

  • reuseaddr - boolean (default true)

  • reuseport - boolean (default false)

  • max_accept - integer (default 64). Bounds accept-drain per readiness event.

  • backlog - integer (default SOMAXCONN)

  • error - coderef (optional). If accept() fails with a non-EAGAIN error.

  • data, edge_triggered, oneshot - forwarded to the listener watcher.

Callback signature:

read => sub ($loop, $client_fh, $listener_watcher) {
  my $server_state = $listener_watcher->data;
  ...
}

Notes:

  • write is not valid for listening sockets and will croak.

  • Accepted sockets are set to nonblocking before callback.

  • This method returns the listening socket; the watcher is returned in list context.

TIMERS

after($seconds, $cb) -> $id

Schedule $cb to run after $seconds. Fractions are allowed. Callback is invoked as $cb->($loop).

at($deadline_seconds, $cb) -> $id

Schedule at an absolute monotonic deadline in seconds (same timebase as Clock).

cancel($id) -> bool

Cancel a scheduled timer by id.

VERSION

0.003_001

AUTHOR

Joshua S. Day and contributors.

LICENSE

Same terms as Perl itself.