NAME

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

SYNOPSIS

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

sub on_message ($pipe, $line) {
    say "received: $line";
}

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

my $pipe = $loop->add(LinePipe->new(
    read_fh => $read,
    data    => { messages => 0 },
));

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.

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 subclass defines:

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

With Linux::Event::Framer, a framed subclass normally defines:

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

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

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. Important options include read_size, read_budget_bytes, read_batch_bytes, message_batch_size, high_watermark, low_watermark, max_pending_bytes, max_buffer, and established timeout values. These are cached once per concrete subclass rather than parsed for each 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.