/ 
Linux-Event-0.117
/ Linux::Event::Framer::Delimiter

NAME

Linux::Event::Framer::Delimiter - Split an ordered byte stream at a delimiter

SYNOPSIS

package LineStream;

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

sub on_message ($self, $message) {
    say "line: $message";
}

DESCRIPTION

Linux::Event::Framer::Delimiter defines messages by a terminating byte sequence.

For example:

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

means that these wire bytes:

hello\nworld\n

produce two messages:

hello
world

Delimiter framing is useful for protocols based on:

"\n"
"\r\n"
"\0"

or any other non-empty byte sequence.

The delimiter may contain arbitrary bytes.

DECLARING THE FRAMER

Declare the framer after the ordered-byte parent class:

package LineStream;

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

The same framer can be used with:

Linux::Event::IO::Sock::Stream
Linux::Event::IO::Pipe
Linux::Event::IO::TTY

because delimiter framing operates on ordered bytes rather than on a particular kind of Linux resource.

THE DELIMITER IS REQUIRED

The first argument after Delimiter is the delimiter byte string:

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

The delimiter must not be empty.

This is invalid:

use Linux::Event::Framer 'Delimiter', '';

An empty delimiter could not define meaningful message boundaries and is rejected during class setup.

DELIMITERS MAY CROSS READ BOUNDARIES

Kernel reads are not application message boundaries.

For example, Linux might deliver:

first read:   "hello\r"
second read:  "\nworld\r\n"

to a CRLF-framed stream.

Linux::Event preserves the partial delimiter and still emits:

hello
world

The application does not need to join read chunks or search for split delimiters itself.

MULTIPLE MESSAGES MAY ARRIVE AT ONCE

One kernel read may contain several complete messages:

one\ntwo\nthree\n

Linux::Event detects all complete frames already present in the ordered-byte input and delivers them through the configured message callback.

The application should therefore think in terms of messages rather than read calls.

RECEIVING MESSAGES

By default, the delimiter itself is removed before delivery:

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

sub on_message ($self, $message) {
    ...
}

For wire input:

hello\n

$message contains:

hello

not:

hello\n

INCLUDING THE DELIMITER

include_delimiter

Set:

use Linux::Event::Framer 'Delimiter', "\r\n",
    include_delimiter => 1;

to include the terminating delimiter in the inbound message.

With wire input:

hello\r\n

the callback receives:

hello\r\n

This option affects inbound message delivery.

It does not change what bytes are consumed from the underlying stream.

LIMITING MESSAGE SIZE

max_frame

An optional max_frame protects against unexpectedly large messages:

use Linux::Event::Framer 'Delimiter', "\n",
    max_frame => 1_048_576;

The limit is measured in payload bytes before the delimiter.

For example, with:

max_frame => 1024

a message whose payload grows beyond 1024 bytes without reaching the configured delimiter is rejected as a framing error.

max_frame must be a non-negative integer.

Omitting it means the Delimiter framer itself does not impose a payload-size limit.

The ordered-byte resource may still have its separate max_buffer limit.

SENDING

For a framed resource:

$self->send($payload);

appends the configured delimiter.

For example:

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

and:

$self->send("hello");

produce these wire bytes:

hello\r\n

The application should normally pass only the payload to send.

Do not manually append the delimiter unless the protocol intentionally requires an additional delimiter.

SEND AND INCLUDE_DELIMITER ARE INDEPENDENT

include_delimiter controls only what is delivered inbound to on_message.

It does not change outbound framing.

For example:

use Linux::Event::Framer 'Delimiter', "\n",
    include_delimiter => 1;

still causes:

$self->send("hello");

to emit exactly:

hello\n

not:

hello\n\n

RAW WRITE

Use:

$self->write($bytes);

when raw bytes should be written without automatically appending the delimiter.

For example:

$self->write("hello");

writes exactly:

hello

while:

$self->send("hello");

writes:

hello<delimiter>

This distinction is useful when implementing protocol handshakes or other special wire sequences.

BINARY DELIMITERS

Delimiter framing is not restricted to text.

For example:

use Linux::Event::Framer 'Delimiter', "\x00\xff";

is valid.

The delimiter is treated as a byte string.

This makes the framer suitable for binary sentinel-based protocols as well as line-oriented text protocols.

EMPTY PAYLOADS

A delimiter may appear with no payload bytes before it.

Conceptually:

<delimiter>

represents an empty framed message.

This is distinct from an empty delimiter, which is not permitted.

ERROR BEHAVIOR

Malformed framing caused by exceeding max_frame is reported through the normal ordered-byte framing error path.

The resulting Linux::Event::Error has type:

framing

The resource then follows its ordinary framing-error lifecycle.

PERFORMANCE MODEL

Inbound delimiter search runs in Linux::Event's native ordered-byte framing engine.

Partial delimiters and incomplete messages remain in native input storage until a complete boundary is found.

There is no per-connection Perl Delimiter object and no need for application code to repeatedly scan accumulated Perl strings for the delimiter.

SEE ALSO

Linux::Event::Framer, Linux::Event::Framer::Fixed, Linux::Event::Framer::LengthPrefix, Linux::Event::IO::Sock::Stream, Linux::Event::IO::Pipe, Linux::Event::IO::TTY, docs/FRAMING.md, docs/CHOOSING-A-FRAMER.md.