NAME

Linux::Event::Framer - native framing for ordered-byte I/O

SYNOPSIS

use Socket qw(AF_UNIX SOCK_STREAM PF_UNSPEC);

package LineSocket;
use parent 'Linux::Event::IO::Sock::Stream';
use Linux::Event::Framer 'Delimiter', "\n";

package main;
socketpair(my $socket, my $peer, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
    or die "socketpair: $!";

my $stream = LineSocket->new(
    fh => $socket,
    on_message => sub ($stream, $message) {
        $stream->send($message);
    },
);

DESCRIPTION

Linux::Event::Framer declares native framing policy for an ordered-byte Linux::Event subclass. Pipes, TTYs, and SOCK_STREAM connections share the same framing engine. The declaration is resolved once per concrete subclass; there is no per-connection framer object.

Framing is class-level wire policy. Application delivery is independent of how that policy is declared: on_message or on_messages may be a class method or a constructor-supplied coderef. A constructor callback does not make the framer per-instance; it only selects that object's effective application CV.

BUILT-IN FRAMERS

Supported declarations include Delimiter, Fixed, LengthPrefix, U32BE, Netstring, Varint, and DecimalLength. Each framer accepts its own framing options; see docs/FRAMING.md and the corresponding framer module POD.

A readable class without a framer needs an effective on_data callback. A framed class normally needs an effective on_message callback, or on_messages when explicit message batching is enabled. In each case the callback may come from a class method or from the object's constructor.

Constructor callbacks are validated during construction and override a same-named method for that object. Input dispatch then invokes one cached effective CV directly from native ordered-byte state; it does not choose between method and closure for every message. The framer itself remains immutable class policy.

NATIVE CONSUMERS

External XS extensions may consume complete framed messages without routing them through a Perl on_message callback:

Linux::Event::Framer->declare_native_consumer(
    'My::FramedConnection',
    {
        provider           => $provider_lifetime_token,
        abi_version        => $abi_version,
        operations_address => $native_table_address,
    },
);

A native consumer may receive complete framed-message SVs, or an unframed provider may request the raw-input ABI and receive a borrowed contiguous native byte window before those bytes are converted to a Perl SV. Raw-input providers report the number of leading bytes consumed; Linux::Event keeps the unconsumed tail in native ordered-byte storage.

transition_to() can retain one provider when source and target share the same operations table, replace one native consumer provider with another, or retire a native consumer into an ordinary Perl input sink while preserving unread native input. Source flush/lifetime obligations are settled before the retiring context is destroyed and the retained tail is re-driven under the target descriptor. Adding a native consumer to an already-ordinary live Stream remains invalid.

This is an extension-author boundary for high-performance protocol and coroutine/awaitable integrations. It is independent of the public Perl class names and must not depend on retired implementation packages.

See docs/ORDERED-BYTE-CONSUMER-ABI.md.

SEE ALSO

docs/FRAMING.md, docs/CHOOSING-A-FRAMER.md, docs/FIRST-CLASS-STREAM-CALLBACKS.md.