Linux::Event

Linux::Event is a Linux-native readiness event loop for Perl. It currently ships with an epoll backend and is built around small Linux kernel primitives: timerfd, signalfd, eventfd, and pidfd.

Linux::Event->new returns a Linux::Event::Loop object directly. Additional readiness backends may be added in future releases.

Architecture

The goal is a small, explicit, composable foundation for building event-driven systems on Linux.

Linux::Event
    |
    +-- Linux::Event::Loop
            |
            +-- Linux::Event::Backend::Epoll
                    |
                    +-- Linux::Event::XS (private hot paths)

What this distribution contains

Core modules in this repository:

• Linux::Event - front door returning Linux::Event::Loop
• Linux::Event::Loop - public readiness loop
• Linux::Event::Backend - readiness backend contract
• Linux::Event::Backend::Epoll - built-in epoll backend
• Linux::Event::Watcher - mutable 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::XS - private XS hot-path implementation

Quick start

use v5.36;
use Linux::Event;

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

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

$loop->run;

You may pass backend => 'epoll' explicitly, but it is also the default:

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

Core API

The loop exposes a focused readiness API:

• watch($fh, read => ..., write => ..., error => ...)
• unwatch($fh)
• after($seconds, $cb)
• at($deadline_seconds, $cb)
• cancel($timer_id)
• signal($signal, $cb, %opts)
• pid($pid, $cb, %opts)
• waker
• run, run_once, stop
• clock, backend, backend_name, is_running

Watcher callbacks receive:

sub ($loop, $fh, $watcher) { ... }

Timer callbacks receive:

sub ($loop) { ... }

Signal callbacks receive:

sub ($loop, $sig, $count, $data) { ... }

Pid callbacks receive:

sub ($loop, $pid, $status, $data) { ... }

Ecosystem layering

This distribution intentionally stays at the loop-and-primitives layer. Companion distributions provide higher-level building blocks:

• Linux::Event::Listen - server-side socket acquisition
• Linux::Event::Connect - client-side nonblocking outbound 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 core loop

Canonical networking composition:

Listen / Connect
        |
      Stream
        |
   your protocol

Implementation notes

The public API is Perl, but the epoll backend uses private XS hot paths for fd registration, reusable epoll event storage, direct watcher dispatch records, and the internal timer heap. These details are private and may change between pre-1.0 releases.

Dependencies

Runtime dependencies are intentionally small:

• Perl 5.36 or newer
• Linux::Event::Timer
• Linux::Event::Clock

Optional feature dependencies are loaded lazily and are only needed when the corresponding feature is used:

• Linux::FD::Event for waker() / eventfd support
• Linux::FD::Signal for signal() / signalfd support
• Linux::FD::Pid for pid() / pidfd support

If an optional feature dependency is missing, the method that needs it throws a clear error naming the missing module and feature.

Examples

See examples/ for small programs covering timers, filehandle readiness, signals, wakeups, pidfds, and reactor regression cases.

Project status

This project is still pre-1.0. The loop is intentionally focused on readiness backends so the stable API can stay small and maintainable.