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

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

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

Dependencies

Runtime dependencies are intentionally small:

• Perl 5.36 or newer
• Linux::Epoll
• Linux::FD::Event
• Linux::FD::Signal
• Linux::FD::Pid
• Linux::Event::Timer
• Linux::Event::Clock

Examples

See examples/ for small programs covering timers, filehandle readiness, signals, wakeups, pidfds, and epoll 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.