---
name: "POE::Filter::Block"
section: "3pm"
platform: "linux"
package: "perl-poe"
version: "1.370-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/POE::Filter::Block"
---

# POE::Filter::Block(3pm)

translate data between streams and blocks

## NAME

POE::Filter::Block - translate data between streams and blocks

## SYNOPSIS

```
  #!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], "\n";
  }
  # Print one line: yz123456
  $filter->get_one_start([ "123456" ]);
  while (1) {
    my $block = $filter->get_one();
    last unless @$block;
    print $block->[0], "\n";
  }
```

## 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.

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 what they get.

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:

```
  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 and a **chr**(0) byte to separate the length from the actual data:

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

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.

```
  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 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 `"MaxBuffer"` parameter.

```
    MaxBuffer => 1099511627776  # One terabyte!
```

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 `"MaxLength"` parameter.

```
    MaxLength => 10             # small blocks
```

Remember that MaxBuffer needs to be larger then MaxLength.  What's more, it needs to have room for the length prefix.

If either the `"MaxLength"` or `"MaxBuffer"` constraint is exceeded, `"POE::Filter::Bock"` will throw an exception.

## PUBLIC FILTER METHODS

POE::Filter::Block has no additional public methods.

## SEE ALSO

Please see POE::Filter for documentation regarding the base interface.

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.