Linux::Event

Linux::Event is a Linux-native event-loop distribution for Perl with two peer execution models:

• Reactor for readiness-based I/O
• Proactor for completion-based I/O

The public front door is Linux::Event::Loop, and Linux::Event->new is a convenient shortcut to it.

<<<<<<< HEAD

Architecture

======= The goal is a small, explicit, composable foundation for building high-performance event-driven systems on Linux. Model selection is explicit and mandatory: choose reactor or proactor when constructing a loop.

1401c31 (prep for cpan and release, new tool added)

Linux::Event::Loop
    |
    +-- Linux::Event::Reactor
    |       |
    |       +-- Linux::Event::Reactor::Backend::Epoll
    |
    +-- Linux::Event::Proactor
            |
            +-- Linux::Event::Proactor::Backend::Uring
            +-- Linux::Event::Proactor::Backend::Fake

What this distribution contains

Core modules in this repository:

• Linux::Event - front door shortcut returning Linux::Event::Loop
• Linux::Event::Loop - selector and delegating public API
• Linux::Event::Reactor - readiness engine
• Linux::Event::Reactor::Backend - readiness backend contract
• Linux::Event::Reactor::Backend::Epoll - epoll backend
• Linux::Event::Watcher - mutable reactor watcher handle
• Linux::Event::Signal - signalfd adaptor
• Linux::Event::Wakeup - eventfd-backed wakeup primitive
• Linux::Event::Pid - pidfd-backed process exit notifications
• Linux::Event::Scheduler - internal monotonic deadline queue
• Linux::Event::Proactor - completion engine
• Linux::Event::Proactor::Backend - completion backend contract
• Linux::Event::Proactor::Backend::Uring - io_uring backend
• Linux::Event::Proactor::Backend::Fake - deterministic testing backend
• Linux::Event::Operation - in-flight operation object
• Linux::Event::Error - lightweight proactor error object

Ecosystem layering

<<<<<<< HEAD This distribution intentionally stays at the loop-and-primitives layer.

Linux::Event Front door for the Linux::Event ecosystem. Construct a Linux::Event::Loop by explicitly choosing reactor or proactor mode.

1401c31 (prep for cpan and release, new tool added)

Companion distributions provide higher-level networking and process-building blocks:

• Linux::Event::Listen - server-side socket acquisition
• Linux::Event::Connect - client-side nonblocking connect
• Linux::Event::Stream - buffered I/O and backpressure for established filehandles
• Linux::Event::Fork - asynchronous child-process helpers
• Linux::Event::Clock - monotonic time helpers
• Linux::Event::Timer - timerfd wrapper used by the reactor

Canonical networking composition:

Listen / Connect
<<<<<<< HEAD
        |
      Stream
        |
   your protocol

=======

  Stream

Application protocol

1401c31 (prep for cpan and release, new tool added)

Choosing a model

<<<<<<< HEAD Use the reactor when you want readiness notifications over existing filehandles:

Linux::Event::Listen Linux::Event::Stream your protocol

1401c31 (prep for cpan and release, new tool added)

use v5.36;
use Linux::Event;

<<<<<<< HEAD
my $loop = Linux::Event->new(model => 'reactor');
=======
Linux::Event::Connect  Linux::Event::Stream  your protocol
>>>>>>> 1401c31 (prep for cpan and release, new tool added)

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

$loop->run;

Use the proactor when you want explicit operation objects and completion callbacks:

use v5.36;
use Linux::Event::Loop;

my $loop = Linux::Event::Loop->new(
  model   => 'proactor',
  backend => 'uring',
);

my $op = $loop->read(
  fh          => $fh,
  len         => 4096,
  on_complete => sub ($op, $result, $data) {
    return if $op->is_cancelled;
    die $op->error->message if $op->failed;

    say "read $result->{bytes} bytes";
  },
);

while ($loop->live_op_count) {
  $loop->run_once;
}

Installation

Development install:

perl Makefile.PL
make
make test
make install

Primary dependencies include:

<<<<<<< HEAD

• Linux
• Linux::Epoll
• Linux::Event::Clock >= 0.011
• Linux::Event::Timer >= 0.010
• IO::Uring and Time::Spec for the real proactor backend ======= Linux Linux::Epoll Linux::Event::Clock >= 0.011 Linux::Event::Timer >= 0.010 IO::Uring and Time::Spec for proactor mode

1401c31 (prep for cpan and release, new tool added)

The proactor test suite also supports a fake backend for deterministic testing.

Examples

The examples/ directory is organized around the current architecture and includes:

<<<<<<< HEAD

• reactor timers, watchers, signals, wakeups, and pidfd examples
• proactor timer, read/write, and socket lifecycle examples
• deeper reactor benchmarking and regression scripts ======= my $loop = Linux::Event->new( model => 'reactor', );

1401c31 (prep for cpan and release, new tool added)

The CI workflow syntax-checks all examples so they do not silently rot.

Status

<<<<<<< HEAD This project is still pre-1.0 and is being actively refined toward a cohesive forward-looking architecture. Large structural cleanup is expected during this stage so the eventual stable API lands in a cleaner shape.

Additional Linux primitives

Linux::Event integrates several Linux kernel facilities.

Signals via signalfd

$loop->signal('INT', sub ($loop, $sig) {
    $loop->stop;
});

Wakeups via eventfd

my $w = $loop->waker(sub ($loop) {
    say "woken";
});

Process exit notifications via pidfd

$loop->pid($pid, sub ($loop, $pid, $status) {
    say "child exited";
});

See the examples/ directory for complete scripts.

Example: TCP server

use v5.36;
use Linux::Event;
use Linux::Event::Listen;
use Linux::Event::Stream;

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

Linux::Event::Listen->new(
    loop => $loop,
    host => '127.0.0.1',
    port => 3000,

    on_accept => sub ($loop, $fh, $peer, $listen) {

        Linux::Event::Stream->new(
            loop => $loop,
            fh   => $fh,

            codec => 'line',

            on_message => sub ($stream, $line) {
                $stream->write_message("echo: $line");
            },
        );
    },
);

$loop->run;

1401c31 (prep for cpan and release, new tool added)

License

Same terms as Perl itself.