NAME
Linux::Event::IO::Sock::Stream - asynchronous Linux SOCK_STREAM connections
SYNOPSIS
package EchoConnection;
use parent 'Linux::Event::IO::Sock::Stream';
use Linux::Event::Framer 'Delimiter', "\n";
sub on_ready ($stream) {
$stream->send('hello');
}
sub on_message ($stream, $message) {
say $message;
$stream->close;
}
package main;
my $connection = $loop->add(EchoConnection->connect(
host => '127.0.0.1',
port => 9999,
));DESCRIPTION
Linux::Event::IO::Sock::Stream is the public class for connected Linux SOCK_STREAM sockets. TCP over IPv4 or IPv6 and Unix-domain stream sockets use the same class; address family is connection configuration rather than a separate type hierarchy.
The class combines the common ordered-byte engine with socket acquisition, addresses, socket policy, kernel half-close semantics, and optional TLS. A concrete protocol subclass supplies named callbacks and, when appropriate, a native framer.
OUTBOUND CONNECTIONS
connect constructs one connection object whose identity is retained through resolution, connection, optional TLS handshake, established I/O, and close:
my $stream = Client->connect(
loop => $loop, # optional immediate attachment
host => 'example.com', # TCP remote host
port => 443, # TCP remote port
timeout => 10, # connection deadline; default 10
data => $state, # optional application state
);Use unix => $path for a filesystem Unix-domain stream socket. Advanced callers may supply a packed sockaddr with its numeric family.
loop is optional. Without it, connect returns a detached object that may later be passed to $loop->add($stream). Writes submitted before readiness use the normal bounded output queue and are delivered in order after the transport becomes usable.
Optional source-side controls include numeric local_host, local_port, and bind_device. Hostname resolution is asynchronous and uses the Loop's private native resolver service.
ADOPTED CONNECTED SOCKETS
new(fh => $socket) adopts an already connected SOCK_STREAM handle. The handle is validated, made nonblocking and close-on-exec, and uses the same established I/O path as an accepted or outbound connection. A TLS-declared class must also specify tls_role for an adopted handle because acquisition cannot infer client versus server role.
CALLBACKS
on_ready($stream) runs once when the connection is application-ready. For TLS that means after handshake and verification, not merely after TCP connect.
A raw subclass defines on_data($stream, $bytes). A framed subclass uses Linux::Event::Framer and defines on_message or, with explicit batching, on_messages.
Optional lifecycle callbacks include on_drain, on_eof, on_error, on_close, and on_transport_ready for transport-specific observation. Callback methods and class policy are resolved into an immutable descriptor so steady-state I/O does not perform method lookup.
FRAMING AND OUTPUT
write($bytes) sends raw ordered bytes. send($payload) applies the subclass's native framer. The native write engine attempts immediate output, queues only unsent bytes, enables writable readiness only while necessary, and uses high/low watermarks plus optional max_pending_bytes protection.
pause_read and resume_read control application reads. transition_to changes protocol callback/framing descriptors in place while retaining the live socket, transport, output queue, and unread native input according to the transition rules in docs/FRAMING.md.
SOCKET POLICY
A subclass may define socket_options for acquisition-time socket policy:
sub socket_options ($class) {
return (
tcp_nodelay => 1,
keepalive => 1,
tcp_user_timeout => 15,
);
}Supported policy includes TCP_NODELAY, keepalive tuning, TCP_USER_TIMEOUT, send/receive buffers, and interface binding where applicable. Constructor values override class policy for one connection. configure_socket is an optional cached cold-path hook for Linux options not covered by the built-ins. See docs/SOCKET-CONFIGURATION.md.
ORDERED-BYTE POLICY AND DEADLINES
stream_options configures read size and fairness, batching, input/output limits, watermarks, and established idle_timeout, read_timeout, and write_timeout. One explicit operation deadline may also be set or changed at runtime. These policies begin when the application transport is usable; DNS, connect, TLS handshake, and TLS shutdown retain their own lifecycle deadlines.
TLS
A stream-socket subclass opts into TLS declaratively:
package SecureClient;
use parent 'Linux::Event::IO::Sock::Stream';
use Linux::Event::TLS
verify => 1,
alpn => ['http/1.1'];Outbound connect selects client mode and derives the default server name from host. A listener that accepts a TLS-declared class selects server mode; that class must declare cert_file and key_file. Framing and callbacks receive plaintext. See Linux::Event::TLS.
ADDRESSES AND LIFECYCLE
local and peer return lazy Linux::Event::Address values when available. fd, fh, state, pending_bytes, and last_error expose connection state without changing ownership.
end drains accepted output then performs the transport's writable half-close. close is immediate and terminal. detach transfers a plain connected socket only when no output is pending; encrypted transports cannot be detached safely.
SEE ALSO
Linux::Event::IO::Sock::Listener, Linux::Event::IO::Sock::Dgram, Linux::Event::Framer, Linux::Event::TLS, docs/SOCKET-CONNECTIONS.md, docs/ORDERED-BYTE-IO-DESIGN.md.