NAME

Linux::Event::Framer - declare native framing for a Stream subclass

SYNOPSIS

package LineStream;
use parent 'Linux::Event::Stream';
use Linux::Event::Framer 'Delimiter', "\n";

sub on_message ($stream, $message) {
    $stream->send($message);
}

DESCRIPTION

The import declares one built-in native framing rule for the calling Stream subclass. The first argument is the exact final component of a package below Linux::Event::Framer. Linux::Event constructs that package name, loads it, validates its definition, and incorporates it into the subclass's cached native descriptor.

There is deliberately no central keyword table and no per-connection framer object. A Stream subclass describes one protocol type; every instance keeps only its changing parser state.

DECLARATIONS

use Linux::Event::Framer 'Delimiter', "\r\n", # required delimiter
    max_frame => 1_048_576;                    # optional

use Linux::Event::Framer 'Fixed',
    size => 32; # required

use Linux::Event::Framer 'LengthPrefix',
    bytes     => 2,         # optional; default 4
    endian    => 'big',     # default
    max_frame => 1_048_576; # optional

use Linux::Event::Framer 'U32BE',
    max_frame => 16 * 1024 * 1024; # optional

use Linux::Event::Framer 'Netstring',
    max_frame => 1_048_576; # optional

use Linux::Event::Framer 'Varint',
    max_frame => 1_048_576; # optional

use Linux::Event::Framer 'DecimalLength',
    separator => ' ',       # default
    max_frame => 1_048_576; # optional

RAW STREAMS

A subclass that does not import a framer is a raw Stream type and must define on_data. A framed subclass must define on_message. See Linux::Event::Stream and docs/FRAMING.md.

EXTENDING THE BUILT-IN FAMILY

The declaration loader derives the implementation package from the final name instead of maintaining a duplicate keyword registry. New native framing semantics still require corresponding XS parser support; arbitrary Perl next_frame objects are not accepted. Applications with unusual protocols should use a raw Stream's on_data, while generally useful framing families can be added to Linux::Event as native built-ins.