.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "POE::Filter::Reference 3"
.TH POE::Filter::Reference 3 "2022-06-02" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POE::Filter::Reference \- freeze and thaw arbitrary Perl data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  #!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:\en", YAML::Dump($_[ARG0]);
\&        print "Bye!\en";
\&        delete $_[HEAP]{io};
\&      }
\&    }
\&  );
\&
\&  POE::Kernel\->run();
\&  exit;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Filter::Reference allows programs to send and receive arbitrary
Perl data structures without worrying about a line protocol.  Its
\&\fBput()\fR method serializes Perl data into a byte stream suitable for
transmission.  \fBget_one()\fR parses the data structures back out of such a
stream.
.PP
By default, POE::Filter::Reference uses Storable to do its magic.  A
different serializer may be specified at construction time.
.SH "PUBLIC FILTER METHODS"
.IX Header "PUBLIC FILTER METHODS"
.SS "new"
.IX Subsection "new"
\&\fBnew()\fR creates and initializes a POE::Filter::Reference object.  It
accepts a list of named parameters.
.PP
\fISerializer\fR
.IX Subsection "Serializer"
.PP
Any class that supports \fBnfreeze()\fR (or \fBfreeze()\fR) and \fBthaw()\fR may be used
as a Serializer.  If a Serializer implements both \fBnfreeze()\fR and
\&\fBfreeze()\fR, then the \*(L"network\*(R" (nfreeze) version will be used.
.PP
Serializer may be a class name:
.PP
.Vb 2
\&  # 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);
.Ve
.PP
Serializer may also be an object:
.PP
.Vb 3
\&  # Use an object.
\&  my $serializer = Data::Serializer::Something\->new();
\&  my $filter = POE::Filter::Reference\->newer( Serializer => $serializer );
.Ve
.PP
If Serializer is omitted or undef, the Reference filter will try to
use Storable, FreezeThaw, and \s-1YAML\s0 in that order.
POE::Filter::Reference will die if it cannot find one of these
serializers, but this rarely happens now that Storable and \s-1YAML\s0 are
bundled with Perl.
.PP
\fICompression\fR
.IX Subsection "Compression"
.PP
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.
.PP
\fIMaxBuffer\fR
.IX Subsection "MaxBuffer"
.PP
\&\f(CW\*(C`MaxBuffer\*(C'\fR sets the maximum amount of data that the filter will hold onto 
while trying to build a new reference.  Defaults to 512 \s-1MB.\s0
.PP
\fINoFatals\fR
.IX Subsection "NoFatals"
.PP
If NoFatals is true, messages will be thawed inside a block eval.  By
default, however, \fBthaw()\fR is allowed to die normally.  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 using NoFatals, it's important to check whether
input is really a reference:
.PP
.Vb 9
\&  sub got_reference {
\&    my $message = $_[ARG0];
\&    if (ref $message) {
\&      print "Got data:\en", YAML::Dump($message);
\&    }
\&    else {
\&      warn "Input decode error: $message\en";
\&    }
\&  }
.Ve
.PP
\&\fBnew()\fR will try to load any classes it needs for \*(L"Compression\*(R" or \*(L"Serializer\*(R".
.SS "new [\s-1SERIALIZER\s0 [, \s-1COMPRESSION\s0 [, \s-1NO_FATALS\s0]]]"
.IX Subsection "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.
.PP
Calling \f(CW\*(C`new\*(C'\fR like this is equivalent to
.PP
.Vb 3
\&    POE::Filter::Reference\->new( Serializer => SERIALIZER,
\&                                 Compression => COMPRESSION,
\&                                 NoFatals  => NO_FATALS );
.Ve
.PP
Please note that if you have a custom serializer class called \f(CW\*(C`Serializer\*(C'\fR
you will have to update your code to the new syntax.
.SH "SERIALIZER API"
.IX Header "SERIALIZER API"
Here's what POE::Filter::Reference expects of its serializers.
.SS "thaw \s-1SERIALIZED\s0"
.IX Subsection "thaw SERIALIZED"
\&\fBthaw()\fR is required.  It accepts two parameters: \f(CW$self\fR and a scalar
containing a \s-1SERIALIZED\s0 byte stream representing a single Perl data
structure.  It returns a reconstituted Perl data structure.
.PP
.Vb 5
\&  sub thaw {
\&    my ($self, $stream) = @_;
\&    my $reference = $self\->_deserialization_magic($stream);
\&    return $reference;
\&  }
.Ve
.SS "nfreeze \s-1REFERENCE\s0"
.IX Subsection "nfreeze REFERENCE"
Either \fBnfreeze()\fR or \fBfreeze()\fR is required.  They behave identically,
except that \fBnfreeze()\fR is guaranteed to be portable across networks and
between machine architectures.
.PP
These freezers accept two parameters: \f(CW$self\fR and a \s-1REFERENCE\s0 to Perl
data.  They return a serialized version of the REFERENCEd data.
.PP
.Vb 5
\&  sub nfreeze {
\&    my ($self, $reference) = @_;
\&    my $stream = $self\->_serialization_magic($reference);
\&    return $stream;
\&  }
.Ve
.SS "freeze \s-1REFERENCE\s0"
.IX Subsection "freeze REFERENCE"
\&\fBfreeze()\fR is an alternative form of \fBnfreeze()\fR.  It has the same call
signature as \fBnfreeze()\fR, but it doesn't guarantee that serialized data
will be portable across machine architectures.
.PP
If you must choose between implementing \fBfreeze()\fR and \fBnfreeze()\fR for use
with POE::Filter::Reference, go with \fBnfreeze()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Please see POE::Filter for documentation regarding the base
interface.
.PP
The \s-1SEE ALSO\s0 section in \s-1POE\s0 contains a table of contents covering
the entire \s-1POE\s0 distribution.
.SH "BUGS"
.IX Header "BUGS"
Not so much bugs as caveats:
.PP
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.
.PP
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.  Make sure the same classes and versions are available
on either end of the wire.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
The Reference filter was contributed by Artur Bergman, with changes
by Philip Gwyn.
.PP
Please see \s-1POE\s0 for more information about authors and contributors.