Linux::Event::Stream

Buffered, backpressure-aware I/O for Linux::Event.

Overview

Linux::Event::Stream wraps a nonblocking file descriptor and provides:

• Write buffering
• High/low watermark backpressure (hysteresis latch)
• Graceful close-after-drain
• Optional read throttling

It does not create sockets, implement protocols, or modify the event loop. It is a small policy layer over a file descriptor.

Designed for use with Linux::Event 0.009+.

Basic Example

use v5.36;
use Linux::Event;
use Linux::Event::Stream;

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

my $stream = Linux::Event::Stream->new(
  loop => $loop,
  fh   => $socket,

  on_read => sub ($stream, $bytes, $data) {
    print "Received: $bytes";
  },

  on_error => sub ($stream, $errno, $data) {
    warn "I/O error: $errno";
  },

  on_close => sub ($stream, $data) {
    print "Connection closed\n";
  },

  high_watermark => 1_048_576,
  low_watermark  =>   262_144,
);

$stream->write("hello\n");

$loop->run;

Framed Example (newline-delimited messages)

Stream can also run in framed/message mode, where it buffers incoming bytes internally and emits complete messages using a codec.

use v5.36;
use Linux::Event;
use Linux::Event::Stream;

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

my $stream = Linux::Event::Stream->new(
  loop       => $loop,
  fh         => $socket,
  codec      => 'line',
  on_message => sub ($stream, $line, $data) {
    $stream->write_message("echo: $line");
  },
);

$loop->run;

Notes

• Raw mode uses C<on_read> and delivers arbitrary byte chunks (TCP and pipes do not preserve message boundaries).
• Framed/message mode uses C<codec + on_message> and delivers complete messages.
• Built-in codec aliases: C, C, C.
• To implement your own framing/encoding, see LLinux::Event::Stream::Codec.