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,
    },
);

This is an extension boundary for high-performance integrations such as coroutine or awaitable layers. 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.