.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Filter::Block 3"
.TH POE::Filter::Block 3 2024-07-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
POE::Filter::Block \- translate data between streams and blocks
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  #!perl
\&
\&  use warnings;
\&  use strict;
\&  use POE::Filter::Block;
\&
\&  my $filter = POE::Filter::Block\->new( BlockSize => 8 );
\&
\&  # Prints three lines: abcdefgh, ijklmnop, qrstuvwx.
\&  # Bytes "y" and "z" remain in the buffer and await completion of the
\&  # next 8\-byte block.
\&
\&  $filter\->get_one_start([ "abcdefghijklmnopqrstuvwxyz" ]);
\&  while (1) {
\&    my $block = $filter\->get_one();
\&    last unless @$block;
\&    print $block\->[0], "\en";
\&  }
\&
\&  # Print one line: yz123456
\&
\&  $filter\->get_one_start([ "123456" ]);
\&  while (1) {
\&    my $block = $filter\->get_one();
\&    last unless @$block;
\&    print $block\->[0], "\en";
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
POE::Filter::Block translates data between serial streams and blocks.
It can handle fixed-length and length-prepended blocks, and it may be
extended to handle other block types.
.PP
Fixed-length blocks are used when Block's constructor is called with a
BlockSize value.  Otherwise the Block filter uses length-prepended
blocks.
.PP
Users who specify block sizes less than one deserve what they get.
.PP
In variable-length mode, a LengthCodec parameter may be specified.
The LengthCodec value should be a reference to a list of two
functions: the length encoder, and the length decoder:
.PP
.Vb 1
\&  LengthCodec => [ \e&encoder, \e&decoder ]
.Ve
.PP
The encoder takes a reference to a buffer and prepends the buffer's
length to it.  The default encoder prepends the ASCII representation
of the buffer's length and a \fBchr\fR\|(0) byte to separate the length from
the actual data:
.PP
.Vb 5
\&  sub _default_encoder {
\&    my $stuff = shift;
\&    substr($$stuff, 0, 0) = length($$stuff) . "\e0";
\&    return;
\&  }
.Ve
.PP
The corresponding decoder returns the block length after removing it
and the separator from the buffer.  It returns nothing if no length
can be determined.
.PP
.Vb 9
\&  sub _default_decoder {
\&    my $stuff = shift;
\&    unless ($$stuff =~ s/^(\ed+)\e0//s) {
\&      warn length($1), " strange bytes removed from stream"
\&        if $$stuff =~ s/^(\eD+)//s;
\&      return;
\&    }
\&    return $1;
\&  }
.Ve
.PP
This filter holds onto incomplete blocks until they are completed in a
framing buffer.  To control memory usage, a maximum framing buffer size is
imposed.  This maximum size defaults to 512 MB (512*1024*1024 octets).  You
may change this size limit with the \f(CW\*(C`MaxBuffer\*(C'\fR parameter.
.PP
.Vb 1
\&    MaxBuffer => 1099511627776  # One terabyte!
.Ve
.PP
The size of each individual block is also limited.  By default, each block
may be no more then 64 MB.  You may change this size limit with the
\&\f(CW\*(C`MaxLength\*(C'\fR parameter.
.PP
.Vb 1
\&    MaxLength => 10             # small blocks
.Ve
.PP
Remember that MaxBuffer needs to be larger then MaxLength.  What's more, it
needs to have room for the length prefix.
.PP
If either the \f(CW\*(C`MaxLength\*(C'\fR or \f(CW\*(C`MaxBuffer\*(C'\fR constraint is exceeded,
\&\f(CW\*(C`POE::Filter::Bock\*(C'\fR will throw an exception.
.SH "PUBLIC FILTER METHODS"
.IX Header "PUBLIC FILTER METHODS"
POE::Filter::Block has no additional public methods.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Please see POE::Filter for documentation regarding the base
interface.
.PP
The SEE ALSO section in POE contains a table of contents covering
the entire POE distribution.
.SH BUGS
.IX Header "BUGS"
The \fBput()\fR method doesn't verify block sizes.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
The Block filter was contributed by Dieter Pearcey, with changes by
Rocco Caputo.
.PP
Please see POE for more information about authors and contributors.