NAME

POE::Filter::Block - filter between streams and blocks

SYNOPSIS

  $filter = POE::Filter::Block->new( BlockSize => 1024 );
  $filter = POE::Filter::Block->new(
    LengthCodec => [ \&encoder, \&decoder ]
  );
  $arrayref_of_blocks =
    $filter->get($arrayref_of_raw_chunks_from_driver);
  $arrayref_of_streamable_chunks_for_driver =
    $filter->put($arrayref_of_blocks);
  $arrayref_of_leftovers =
    $filter->get_pending();

DESCRIPTION

The Block filter translates data between serial streams and blocks. It can handle two kinds of block: fixed-length and length-prepended.

Fixed-length blocks are used when Block's constructor is called with a BlockSize value. Otherwise the Block filter uses length-prepended blocks.

Users who specify block sizes less than one deserve to be soundly spanked.

In variable-length mode, a LengthCodec parameter is valid. The LengthCodec should be a list reference of two functions: The length encoder, and the length decoder:

  LengthCodec => [ \&encoder, \&decoder ]

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. The length is separated from the buffer by an ASCII NUL ("\0") character.

  sub _default_encoder {
    my $stuff = shift;
    substr($$stuff, 0, 0) = length($$stuff) . "\0";
    return;
  }

Sensibly enough, the corresponding decoder removes the prepended length and separator, returning its numeric value. It returns nothing if no length can be determined.

  sub _default_decoder {
    my $stuff = shift;
    unless ($$stuff =~ s/^(\d+)\0//s) {
      warn length($1), " strange bytes removed from stream"
        if $$stuff =~ s/^(\D+)//s;
      return;
    }
    return $1;
  }

This filter holds onto incomplete blocks until they are completed.

PUBLIC FILTER METHODS

Please see POE::Filter.

SEE ALSO

POE::Filter.

The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.

BUGS

The put() method doesn't verify block sizes.

AUTHORS & COPYRIGHTS

The Block filter was contributed by Dieter Pearcey, with changes by Rocco Caputo.

Please see POE for more information about authors and contributors.