/ 
Linux-Event-0.103
/ Linux::Event

NAME

Linux::Event - Linux-native reactor, streams, datagrams, and processes

SYNOPSIS

use Linux::Event::Loop;
use Linux::Event::Stream;

my $loop = Linux::Event::Loop->new;
$loop->add(MyStream->connect(
    host => '127.0.0.1', # required
    port => 9999,        # required
));
$loop->run;

DESCRIPTION

Linux::Event is a Linux-only asynchronous I/O distribution. The XS-first Linux::Event::Loop reactor owns native descriptor registrations. Public Stream, Listener, Datagram, Timer, Signal, Wakeup, and Process objects own their logical resources and attach directly to one Loop; they do not inherit from a generic Watcher or IO class.

The APIs deliberately remain layered. Applications that need raw descriptor readiness can use the reactor directly. Applications that want automatic socket reads, buffered writes, and native message framing can use a Stream subclass on top.

Every attachable public object accepts loop => $loop. It can instead be constructed detached and passed to $loop->add($object). add sets the Loop, starts the object's activity, and returns the same object.

MAIN MODULES

  • Linux::Event::Loop

    XS-first epoll reactor and native watcher registry.

  • Linux::Event::Stream

    Subclass-defined buffered byte streams with connection, framing, backpressure, half-close, established deadlines, protocol-transition, and transport lifecycle.

  • Linux::Event::Listener

    TCP and Unix listeners that automatically construct a chosen Stream subclass.

  • Linux::Event::Datagram

    Connected and unconnected UDP and Unix datagram sockets that preserve packet boundaries and peer addresses.

  • Linux::Event::Timer

    Subclass-defined one-shot and fixed-rate recurring monotonic timers.

  • Linux::Event::Signal

    Subclass-defined synchronous signalfd subscriptions with native fan-out.

  • Linux::Event::Wakeup

    Subclass-defined eventfd notifications that foreign threads or forked children may signal without transferring Perl callbacks or values.

  • Linux::Event::Process

    pidfd lifecycle notification, native process spawning, decoded exit status, signals, and asynchronous standard I/O.

  • Linux::Event::TLS

    Declarative OpenSSL TLS policy for Stream subclasses.

  • Linux::Event::Framer

    Guide to selecting a framing strategy for message-oriented protocols.

  • Linux::Event::Error

    Structured errors shared by socket, process, connection, and transport paths.

  • Linux::Event::Address

    Lazy IPv4, IPv6, and Unix socket-address values.

PUBLIC MODEL

Applications subclass Linux::Event::Stream and Linux::Event::Datagram to define network behavior, Linux::Event::Timer to define scheduled behavior, Linux::Event::Signal to define signal behavior, Linux::Event::Wakeup to define notification handling, and Linux::Event::Process to define child lifecycle handling. They do not subclass Loop registrations. Outbound Stream acquisition is MyStream->connect(host => '127.0.0.1', port => 9999). Inbound Stream acquisition is Linux::Event::Listener->new(stream_class => 'MyStream', host => '0.0.0.0', port => 9999). A Stream subclass opts into TLS with use Linux::Event::TLS; connect and Listener acceptance select the client or server handshake role.

$loop->watch(fd => $fd, read => $callback) remains available for low-level descriptor readiness. It immediately returns an opaque native registration handle with methods such as cancel, enable_read, and disable_write. That handle is not a named public class or a subclassing contract.

PLATFORM

Linux only. Building the complete distribution requires Linux headers with pidfd syscall definitions, a Linux 5.4 or newer runtime for pidfd status, a libc providing posix_spawn_file_actions_addchdir_np, and OpenSSL 1.1.1 or newer development files. Perl ithreads are not required.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.