/ 
Linux-Event-0.112
/ Linux::Event::IO::Pipe

NAME

Linux::Event::IO::Pipe - asynchronous ordered-byte I/O for pipes and FIFOs

SYNOPSIS

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

package LinePipe;
use parent 'Linux::Event::IO::Pipe';
use Linux::Event::Framer 'Delimiter', "\n";

package main;
pipe(my $read, my $write) or die "pipe: $!";

my $loop = Linux::Event::Loop->new;
my $prefix = 'received';
my $pipe = LinePipe->new(
    loop       => $loop,
    read_fh    => $read,
    on_message => sub ($pipe, $line) {
        say "$prefix: $line";
        $pipe->close;
        $loop->stop;
    },
);

syswrite($write, "hello\n") == 6 or die "syswrite: $!";
$loop->run;
close $write;

DESCRIPTION

Linux::Event::IO::Pipe is the public ordered-byte I/O class for anonymous pipes and FIFOs. It uses the same native buffering, framing, output queue, backpressure, deadlines, and directional lifecycle as the other ordered-byte Linux::Event leaves without giving a pipe socket semantics.

A Pipe may be read-only, write-only, or duplex. Duplex operation may use two different descriptors, which is useful for child stdin/stdout pairs and other one-way pipe combinations.

CALLBACKS, SUBCLASSING, AND TUNING

Constructor callbacks let one Pipe capture lexical application state. A subclass becomes more valuable when many pipes share protocol policy: it can declare a native Linux::Event::Framer, centralize stream_options tuning, and provide named callbacks. For example, the Synopsis deliberately combines a delimiter-framing subclass with a lexical on_message closure.

stream_options controls read size and fairness, callback batching, buffer and output limits, watermarks, and established deadlines. Framer and tuning policy are validated and cached once per subclass. Constructor callbacks override same-named methods for one Pipe and are cached once per object, so the hot input path does not perform method lookup or callback-style selection.

TLS does not apply to Pipe; TLS transport policy is specific to Linux::Event::IO::Sock::Stream.

stream_options

Define stream_options as a class method on the Pipe subclass. It returns key/value pairs, or one hash reference:

package BulkPipe;
use parent 'Linux::Event::IO::Pipe';

sub stream_options ($class) {
    return (
        read_size         => 131_072,
        read_budget_bytes => 524_288,
        max_buffer        => 16_777_216,
    );
}

The complete option set is:

  • read_size (default 65,536)

    Maximum bytes requested by one native read; a positive integer.

  • read_budget_bytes (default 0)

    Maximum bytes read during one readiness drain. Zero drains until the input would block.

  • read_batch_bytes (default 0)

    For an unframed class, combine successful reads before on_data up to this non-negative byte target. A partial batch flushes when the current drain ends; zero preserves normal read callback boundaries. It is invalid on a framed class.

  • message_batch_size (default 0)

    For a framed class, deliver arrays of at most this many messages to on_messages. A partial batch flushes when the current drain ends; zero uses on_message. A positive value requires on_messages and is invalid on an unframed class.

  • max_buffer (default 8,388,608)

    Positive hard byte bound for retained input, an incomplete frame, and the aggregate payload retained for one message batch.

  • high_watermark (default 1,048,576)

    Non-negative pending-output byte level at which write or send begins returning false while still accepting the data.

  • low_watermark (default 262,144)

    Non-negative pending-output byte level at or below which on_drain fires after high-watermark backpressure. It must not exceed high_watermark.

  • max_pending_bytes (default 0)

    Hard non-negative pending-output byte limit. Zero means unbounded.

  • idle_timeout (default 0 seconds)

    Maximum inactivity interval since successful input or output progress. Zero disables it.

  • read_timeout (default 0 seconds)

    Maximum interval without inbound progress while reading is active. Pausing input suspends it; zero disables it.

  • write_timeout (default 0 seconds)

    Maximum interval without output progress while data is queued. Zero disables it.

Byte counts are integers. Timeout values are finite non-negative seconds and may be fractional. Constructor timeout values override class defaults for one Pipe; the other values are class policy.

CONSTRUCTION

new accepts exactly one of these handle shapes:

MyPipe->new(fh => $duplex_handle);
MyPipe->new(read_fh => $input, write_fh => $output);
MyPipe->new(read_fh => $input);
MyPipe->new(write_fh => $output);

fh means that one descriptor supplies both directions and cannot be combined with read_fh or write_fh. Every supplied handle must be a Linux pipe or FIFO. Linux::Event validates that identity before generic ordered-byte setup, then makes owned descriptors nonblocking and close-on-exec.

loop => $loop attaches immediately. Otherwise construct detached and pass the object to $loop->add($pipe). data stores arbitrary application state.

Ordered-byte deadline overrides idle_timeout, read_timeout, and write_timeout, plus an explicit deadline, are also accepted. See docs/ORDERED-BYTE-DEADLINES.md.

INPUT CALLBACKS

A readable unframed Pipe requires, as a subclass method or constructor option:

sub on_data ($pipe, $bytes) { ... }

With Linux::Event::Framer, a framed Pipe similarly requires:

sub on_message ($pipe, $message) { ... }

or on_messages($pipe, $messages) when message_batch_size is enabled. Optional lifecycle callbacks are on_drain($pipe), on_eof($pipe), on_error($pipe, $error), and on_close($pipe).

Each callback may instead be supplied as a coderef to new. Constructor callbacks override class methods for that Pipe and retain ordinary Perl lexical scope. Input callbacks are cached in the same native ordered-byte state as method callbacks rather than looked up for each read or message.

OUTPUT AND LIFECYCLE

write($bytes) queues raw bytes. send($payload) applies the subclass's framer when one is declared. High/low watermarks provide cooperative backpressure and max_pending_bytes can impose a hard queue bound.

pause_read and resume_read control input delivery. end drains accepted output and ends the writable direction. close_read and close_write stop one direction immediately; close terminates the whole object.

detach requires an empty output queue and transfers the still-open handles back to the caller as a hash containing read_fh and write_fh. It is a terminal ownership transfer and does not invoke on_close.

CLASS POLICY

Subclasses may define stream_options for the shared ordered-byte engine. The complete option contract appears near the top of this document. These values are cached once per concrete subclass rather than parsed per instance.

Framing is valid for pipes because framing describes ordered application bytes, not sockets. See Linux::Event::Framer and docs/FRAMING.md.

SEE ALSO

Linux::Event::IO::TTY, Linux::Event::IO::Sock::Stream, Linux::Event::Loop, docs/ORDERED-BYTE-IO-DESIGN.md.