POE::Filter::Reference - freeze and thaw arbitrary Perl data
#!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;
POE::Filter::Reference allows programs to send and receive arbitrary
Perl data structures without worrying about a line protocol. Its
put() method serializes Perl data into a byte stream suitable for
transmission. get_one() parses the data structures back out of such a
stream.
By default, POE::Filter::Reference uses Storable to do its magic. A
different serializer may be specified at construction time.
new() creates and initializes a POE::Filter::Reference object. It
accepts a list of named parameters.
Any class that supports nfreeze() (or freeze()) and thaw() may be used
as a Serializer. If a Serializer implements both nfreeze() and
freeze(), then the ``network'' (nfreeze) version will be used.
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, FreezeThaw, and YAML in that order.
POE::Filter::Reference will die if it cannot find one of these
serializers, but this rarely happens now that Storable and YAML are
bundled with Perl.
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.
MaxBuffer sets the maximum amount of data that the filter will hold onto
while trying to build a new reference. Defaults to 512 MB.
If NoFatals is true, messages will be thawed inside a block eval. By
default, however, thaw() 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:
sub got_reference {
my $message = $_[ARG0];
if (ref $message) {
print "Got data:\n", YAML::Dump($message);
}
else {
warn "Input decode error: $message\n";
}
}
new() will try to load any classes it needs for Compression or Serializer.
This is the old constructor synatx. It does not conform to the normal
POE::Filter constructor parameter syntax. Please use the new syntax
instead.
Calling new like this is equivalent to
POE::Filter::Reference->new( Serializer => SERIALIZER,
Compression => COMPRESSION,
NoFatals => NO_FATALS );
Please note that if you have a custom serializer class called Serializer
you will have to update your code to the new syntax.
Here's what POE::Filter::Reference expects of its serializers.
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.
sub thaw {
my ($self, $stream) = @_;
my $reference = $self->_deserialization_magic($stream);
return $reference;
}
Either nfreeze() or freeze() is required. They behave identically,
except that nfreeze() is guaranteed to be portable across networks and
between machine architectures.
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() 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.
If you must choose between implementing freeze() and nfreeze() for use
with POE::Filter::Reference, go with nfreeze().
Please see the POE::Filter manpage for documentation regarding the base
interface.
The SEE ALSO section in POE contains a table of contents covering
the entire POE distribution.
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.
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.
The Reference filter was contributed by Artur Bergman, with changes
by Philip Gwyn.
Please see POE for more information about authors and contributors.
|