NAME

Linux::Event::Reactor - Readiness-based event loop engine for Linux::Event

SYNOPSIS

use v5.36;
use Linux::Event;

my $loop = Linux::Event->new(
  model   => 'reactor',
  backend => 'epoll',
);

$loop->after(0.100, sub ($loop) {
  say "timer fired";
});

my $watcher = $loop->watch(
  $fh,
  read => sub ($loop, $fh, $watcher) {
    my $buf = '';
    my $n = sysread($fh, $buf, 8192);

    if (!defined $n) {
      die "sysread failed: $!";
    }

    if ($n == 0) {
      $watcher->cancel;
      $loop->stop;
      return;
    }

    print $buf;
  },
);

$loop->run;

DESCRIPTION

Linux::Event::Reactor is the readiness engine in this distribution. It is built around epoll readiness notifications plus Linux-native primitives for monotonic timers, signals, wakeups, and pidfds.

It is deliberately small and explicit:

• it watches filehandles for readiness

• it schedules timers in monotonic time

• it adapts Linux signal, wakeup, and pid primitives into the loop

• it does not own socket acquisition or buffered stream policy

Higher-level networking remains in companion distributions such as Linux::Event::Listen, Linux::Event::Connect, and Linux::Event::Stream.

CONSTRUCTOR

new(%args)

Recognized arguments:

• backend

  Backend name or backend object. The built-in backend is epoll.

• clock

  Clock object. It must provide tick, now_ns, deadline_in_ns, and remaining_ns.

• timer

  Timer object. It must provide after, disarm, read_ticks, and fh.

• loop

  Optional public loop facade. This is used internally when the reactor is constructed by Linux::Event::Loop so callbacks receive the public loop object rather than the engine object.

LIFECYCLE

run

Enter the event loop and keep running until stop is called.

run_once($timeout_s = undef)

Advance the loop by one iteration. Due timer callbacks are dispatched first; then the backend wait is entered if appropriate.

$timeout_s is in seconds and may be fractional.

stop

Stop a running loop. If a wakeup object has already been created, the reactor signals it so a blocking backend wait can return promptly.

is_running

True while run is actively looping.

TIMERS

after($seconds, $cb)

Schedule $cb to run after a relative monotonic delay.

at($deadline_seconds, $cb)

Schedule $cb for an absolute monotonic deadline expressed in seconds.

cancel($timer_id)

Cancel a timer previously returned by after or at.

Timer callbacks are invoked as:

$cb->($loop)

WATCHERS

watch($fh, %spec)

Register a watcher for a filehandle. Recognized keys in %spec:

• read

• write

• error

• data

• edge_triggered

• oneshot

Returns a Linux::Event::Watcher.

Watcher callbacks receive:

$cb->($loop, $fh, $watcher)

The dispatch rules are intentionally explicit:

• error runs first if an error handler is installed and enabled

• otherwise an error condition is treated as readable and writable

• hup also makes the watcher readable so EOF can be observed

unwatch($fh)

Remove the watcher for the given filehandle, if one exists.

SIGNALS, WAKEUPS, AND PIDFDS

signal(...)

Returns the loop-owned Linux::Event::Signal adaptor and subscribes a signal handler.

waker

Returns the loop-owned Linux::Event::Wakeup object. The reactor installs an internal watcher that drains the eventfd so stop and explicit signals can wake backend waits promptly.

pid(...)

Returns a pid subscription using the loop-owned Linux::Event::Pid adaptor.

ACCESSORS

clock

Returns the clock object.

timer

Returns the timer object.

backend

Returns the reactor backend object.

backend_name

Returns the backend name.

sched

Returns the internal scheduler object.

SEE ALSO

Linux::Event::Loop, Linux::Event::Watcher, Linux::Event::Signal, Linux::Event::Wakeup, Linux::Event::Pid, Linux::Event::Reactor::Backend, Linux::Event::Reactor::Backend::Epoll

cpanm Linux::Event

perl -MCPAN -e shell
install Linux::Event