NAME

Linux::Event::IO::TTY - asynchronous ordered-byte I/O for terminals and PTYs

SYNOPSIS

package Console;
use parent 'Linux::Event::IO::TTY';
use Linux::Event::Framer 'Delimiter', "\n";

sub on_message ($tty, $line) {
    $tty->write("You typed: $line\n");
}

package main;
my $console = $loop->add(Console->new(
    read_fh  => \*STDIN,
    write_fh => \*STDOUT,
));

DESCRIPTION

Linux::Event::IO::TTY is the public ordered-byte I/O class for terminals and pseudo-terminals. It is appropriate for interactive standard input/output, PTY-backed subprocess interfaces, and other terminal handles that should use Linux::Event's native buffering and readiness machinery.

TTY owns asynchronous byte movement; it does not configure terminal modes, echo, canonical input, baud rates, or other termios policy. Applications that need those settings configure the terminal separately.

CONSTRUCTION

new accepts a shared fh, separate read_fh and write_fh, or either direction alone. Every supplied handle must be a TTY or PTY according to Perl's -t test. Separate input and output handles are intentionally supported, so STDIN and STDOUT can form one logical terminal object.

loop => $loop attaches immediately; detached objects may instead be passed to $loop->add($tty). data stores application state. Owned handles are made nonblocking and close-on-exec.

Established idle_timeout, read_timeout, write_timeout, and explicit deadline options use the common ordered-byte deadline model.

CALLBACKS AND FRAMING

A raw readable subclass defines on_data($tty, $bytes). A subclass that uses Linux::Event::Framer defines on_message($tty, $message) or, with explicit batching, on_messages($tty, $messages).

Delimiter framing is especially useful for line-oriented interactive input:

use Linux::Event::Framer 'Delimiter', "\n";

Framing operates on the bytes Linux supplies after the terminal's own line discipline. Linux::Event does not change canonical/raw terminal mode merely because a framer is declared.

Optional lifecycle callbacks are on_eof, on_drain, on_error, and on_close.

OUTPUT AND LIFECYCLE

write submits raw bytes; send applies the declared framer. Native output queues preserve ordering and provide high/low-watermark backpressure.

pause_read and resume_read control application input. end drains the writable side, while close_read, close_write, and close provide immediate directional or whole-object termination.

detach transfers still-open directional handles to the caller when no output is queued. It is terminal and does not call on_close.

CLASS POLICY

stream_options configures the common ordered-byte engine. The main controls are read_size, read_budget_bytes, raw-read or framed-message batching, input/output limits, watermarks, and established deadlines. Policy is cached per subclass so ordinary readiness does not perform option parsing or callback lookup.

SEE ALSO

Linux::Event::IO::Pipe, Linux::Event::IO::Sock::Stream, Linux::Event::Framer, docs/ORDERED-BYTE-IO-DESIGN.md.