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

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.

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.