POE::F...:Block(3pm)

💖 POE::Filter::Block 💖

okay bestie, welcome to POE::Filter::Block — the little Perl module that translates data between streams and blocks. That's the whole vibe. Streams go in, blocks come out, and vice versa. slay. 🦋

---

✨ 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";
}

like… look at that. "y" and "z" just sitting there in the buffer, waiting for their moment. main character energy fr. 👑

---

🌸 DESCRIPTION 🌸

POE::Filter::Block takes data and flips it between serial streams and blocks. That's it, that's the job. It handles fixed-length blocks and length-prepended blocks, and — icon behaviour — you can extend it to handle other block types too. 🎀

You get fixed-length blocks when you call Block's constructor with a BlockSize value. If you don't, the Block filter goes with length-prepended blocks instead. Simple as.

and if you specify a block size less than one? bestie. "Users who specify block sizes less than one deserve what they get." that's a direct quote, i don't make the rules 💀

In variable-length mode, you can pass a LengthCodec parameter. Its 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, plus 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. If it can't figure out a length, it returns nothing. nada. zilch. 🙈

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're completed in a framing buffer. Which, okay, memory anxiety — so there's a maximum framing buffer size imposed. By default that max is 512 MB (512*1024*1024 octets). You can change the limit with the "MaxBuffer" parameter:

MaxBuffer => 1099511627776  # One terabyte!

The size of each individual block is limited too. By default, each block can be no more than 64 MB. Change that limit with the "MaxLength" parameter:

MaxLength => 10             # small blocks

⚠️ remember, bestie: MaxBuffer needs to be larger than MaxLength. And not just barely — it needs room for the length prefix too. fr fr.

If either the "MaxLength" or "MaxBuffer" constraint gets exceeded, "POE::Filter::Bock" will throw an exception. no cap. 💅

---

👑 PUBLIC FILTER METHODS 👑

POE::Filter::Block has no additional public methods. that's it. nothing extra. it's giving minimalist. ✨

---

🌈 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. it's the whole map, iykyk. 🗺️

---

💀 BUGS 💀

The put() method doesn't verify block sizes. yeah. it just doesn't. be aware. 😭

---

💜 AUTHORS & COPYRIGHTS 💜

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

Please see POE for more information about authors and contributors.

---

and that's the whole page, bestie — this one's from perl v5.34.0, dated 2022-03-25, brought to you by the fine folks in the User Contributed Perl Documentation. go forth and frame your blocks. mwah 💋