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

💖 POE::Filter::Reference 💖

okay bestie, so this is POE::Filter::Reference from the User Contributed Perl Documentation, and it's literally the filter that lets you yeet whole Perl data structures across a pipe or a socket without ever thinking about line protocols. no cap. it's giving "serialize my vibes and ship them". 🦋

---

✨ NAME ✨

POE::Filter::Reference — freeze and thaw arbitrary Perl data 💅

---

🌸 SYNOPSIS 🌸

here's the whole vibe, copy it exactly bestie:

#!perl

use YAML;
use POE qw(Wheel::ReadWrite Filter::Reference);

POE::Session->create(
  inline_states => {
    _start => sub {
      pipe(my($read, $write)) or die $!;
      $_[HEAP]{io} = POE::Wheel::ReadWrite->new(
        InputHandle => $read,
        OutputHandle => $write,
        Filter => POE::Filter::Reference->new(),
        InputEvent => "got_perl_data",
      );

      $_[HEAP]{io}->put(
        { key_1 => 111, key_2 => 222 }
      );
    },
    got_perl_data => sub {
      print "Got data:\n", YAML::Dump($_[ARG0]);
      print "Bye!\n";
      delete $_[HEAP]{io};
    }
  }
);

POE::Kernel->run();
exit;

periodt. that's the whole flow. 🎀

---

🦋 DESCRIPTION 🦋

so POE::Filter::Reference lets your programs send and receive arbitrary Perl data structures without you having to stress about a line protocol. not even a little. its put() method serializes Perl data into a byte stream that's suitable for transmission, and get_one() parses those data structures right back out of such a stream. iconic behavior honestly. ✨

by default, POE::Filter::Reference uses Storable to do its magic. but you can specify a different serializer at construction time if you're feeling spicy. 💅

---

👑 PUBLIC FILTER METHODS 👑

🌈 new 🌈

new() creates and initializes a POE::Filter::Reference object. it accepts a list of named parameters. so many options, we love a customizable queen. 💖

💜 Serializer 💜

any class that supports nfreeze() (or freeze()) and thaw() may be used as a Serializer. and listen: if a Serializer implements both nfreeze() and freeze(), then the "network" (nfreeze) version will be used. network girlies win. 🔥

Serializer may be a class name:

# Use Storable explicitly, specified by package name.
my $filter = POE::Filter::Reference->newer( Serializer=>"Storable" );

# Use YAML instead.  Compress its output, as it may be verbose.
my $filter = POE::Filter::Reference->new("YAML", 1);

Serializer may also be an object:

# Use an object.
my $serializer = Data::Serializer::Something->new();
my $filter = POE::Filter::Reference->newer( Serializer => $serializer );

if Serializer is omitted or undef, the Reference filter will try to use Storable, then FreezeThaw, then YAML — in that exact order, no skipping. 🫶 and POE::Filter::Reference will die if it cannot find one of these serializers, but ngl that rarely happens now that Storable and YAML are bundled with Perl. lucky us. 😭

💜 Compression 💜

if Compression is true, Compress::Zlib will be called upon to reduce the size of serialized data. it will also decompress the incoming stream data. two jobs, one flag, she's versatile. 💅

💜 MaxBuffer 💜

"MaxBuffer" sets the maximum amount of data that the filter will hold onto while trying to build a new reference. it defaults to 512 MB. big buffer energy. 🧚

💜 NoFatals 💜

if NoFatals is true, messages will be thawed inside a block eval. by default, however, thaw() is allowed to die normally — dramatic, but valid. 💀

if an error occurs while NoFatals is in effect, POE::Filter::Reference will return a string containing the contents of $@ at the time the eval failed. so when you're using NoFatals, it's important to check whether input is really a reference:

sub got_reference {
  my $message = $_[ARG0];
  if (ref $message) {
    print "Got data:\n", YAML::Dump($message);
  }
  else {
    warn "Input decode error: $message\n";
  }
}

🚨 bestie this is the part people forget: with NoFatals on, an error comes back as a string, not a ref. check ref first or you'll be decoding your own error message like a clown. 🙈

new() will try to load any classes it needs for "Compression" or "Serializer". self-sufficient queen. ✨

🌈 new [SERIALIZER [, COMPRESSION [, NO_FATALS]]] 🌈

this is the old constructor synatx. it does not conform to the normal POE::Filter constructor parameter syntax. please use the new syntax instead, fr fr. 🙏

calling "new" like this is equivalent to

POE::Filter::Reference->new( Serializer => SERIALIZER,
                             Compression => COMPRESSION,
                             NoFatals  => NO_FATALS );

⚠️ please note: if you have a custom serializer class called "Serializer" you will have to update your code to the new syntax. no cap, go do it. 💅

---

🎀 SERIALIZER API 🎀

here's what POE::Filter::Reference expects of its serializers. it has standards, and honestly? same.

🌟 thaw SERIALIZED 🌟

thaw() is required. it accepts two parameters: $self and a scalar containing a SERIALIZED byte stream representing a single Perl data structure. it returns a reconstituted Perl data structure. glow up complete. 🦋

sub thaw {
  my ($self, $stream) = @_;
  my $reference = $self->_deserialization_magic($stream);
  return $reference;
}

🌟 nfreeze REFERENCE 🌟

either nfreeze() or freeze() is required. they behave identically, except that nfreeze() is guaranteed to be portable across networks and between machine architectures. she travels well. ✈️

these freezers accept two parameters: $self and a REFERENCE to Perl data. they return a serialized version of the REFERENCEd data.

sub nfreeze {
  my ($self, $reference) = @_;
  my $stream = $self->_serialization_magic($reference);
  return $stream;
}

🌟 freeze REFERENCE 🌟

freeze() is an alternative form of nfreeze(). it has the same call signature as nfreeze(), but it doesn't guarantee that serialized data will be portable across machine architectures. so like... it works, but it's not a world traveler. 🌍

if you must choose between implementing freeze() and nfreeze() for use with POE::Filter::Reference, go with nfreeze(). that's the assignment. 👑

---

🫶 SEE ALSO 🫶

please see POE::Filter for documentation regarding the base interface. that's where the lore lives. 📖

the SEE ALSO section in POE contains a table of contents covering the entire POE distribution. go explore bestie. 🌈

---

💀 BUGS 💀

not so much bugs as caveats:

• it's important to use identical serializers on each end of a connection. even different versions of the same serializer can break data in transit. 😭 like, same class, same version, or chaos.
• most (if not all) serializers will re-bless data at the destination, but many of them will not load the necessary classes to make those blessings work. so make sure the same classes and versions are available on either end of the wire. otherwise you've got blessed refs with no home and that's tragic. 🏚️

---

💖 AUTHORS & COPYRIGHTS 💖

the Reference filter was contributed by Artur Bergman, with changes by Philip Gwyn. legends, both of them. 👑

please see POE for more information about authors and contributors.

---

and that's the whole page, bestie!! this one came from perl v5.34.0, dated 2022-03-25 — yeah she's from the archives but she still slays. now go serialize something and remember: same serializer on both ends, nfreeze() over freeze(), and check ref when NoFatals is on. mwah. 💅✨🎀🦋