POE::Filter::Reference(3pm)

1POE::Filter::Reference(U3s)er Contributed Perl DocumentatPiOoEn::Filter::Reference(3)
2
3
4

NAME

6       POE::Filter::Reference - freeze and thaw arbitrary Perl data
7

SYNOPSIS

9         #!perl
10
11         use YAML;
12         use POE qw(Wheel::ReadWrite Filter::Reference);
13
14         POE::Session->create(
15           inline_states => {
16             _start => sub {
17               pipe(my($read, $write)) or die $!;
18               $_[HEAP]{io} = POE::Wheel::ReadWrite->new(
19                 InputHandle => $read,
20                 OutputHandle => $write,
21                 Filter => POE::Filter::Reference->new(),
22                 InputEvent => "got_perl_data",
23               );
24
25               $_[HEAP]{io}->put(
26                 { key_1 => 111, key_2 => 222 }
27               );
28             },
29             got_perl_data => sub {
30               print "Got data:\n", YAML::Dump($_[ARG0]);
31               print "Bye!\n";
32               delete $_[HEAP]{io};
33             }
34           }
35         );
36
37         POE::Kernel->run();
38         exit;
39

DESCRIPTION

41       POE::Filter::Reference allows programs to send and receive arbitrary
42       Perl data structures without worrying about a line protocol.  Its put()
43       method serializes Perl data into a byte stream suitable for
44       transmission.  get_one() parses the data structures back out of such a
45       stream.
46
47       By default, POE::Filter::Reference uses Storable to do its magic.  A
48       different serializer may be specified at construction time.
49

PUBLIC FILTER METHODS

51       POE::Filter::Reference deviates from the standard POE::Filter API in
52       the following ways.
53
54   new [SERIALIZER [, COMPRESSION]]
55       new() creates and initializes a POE::Filter::Reference object.  It will
56       use Storable as its default SERIALIZER if none other is specified.
57
58       If COMPRESSION is true, Compress::Zlib will be called upon to reduce
59       the size of serialized data.  It will also decompress the incoming
60       stream data.
61
62       Any class that supports nfreeze() (or freeze()) and thaw() may be used
63       as a SERIALIZER.  If a SERIALIZER implements both nfreeze() and
64       freeze(), then the "network" version will be used.
65
66       SERIALIZER may be a class name:
67
68         # Use Storable explicitly, specified by package name.
69         my $filter = POE::Filter::Reference->new("Storable");
70
71         # Use YAML instead.  Compress its output, as it may be verbose.
72         my $filter = POE::Filter::Reference->new("YAML", 1);
73
74       SERIALIZER may also be an object:
75
76         # Use an object.
77         my $serializer = Data::Serializer::Something->new();
78         my $filter = POE::Filter::Reference->new($serializer);
79
80       If SERIALIZER is omitted or undef, the Reference filter will try to use
81       Storable, FreezeThaw, and YAML in that order.  POE::Filter::Reference
82       will die if it cannot find one of these serializers, but this rarely
83       happens now that Storable and YAML are bundled with Perl.
84
85         # A choose-your-own-serializer adventure!
86         # We'll still deal with compressed data, however.
87         my $filter = POE::Filter::Reference->new(undef, 1);
88
89       POE::Filter::Reference will try to compress frozen strings and
90       uncompress them before thawing if COMPRESSION is true.  It uses
91       Compress::Zlib for this.  POE::Filter::Reference doesn't need
92       Compress::Zlib if COMPRESSION is false.
93
94       new() will try to load any classes it needs.
95

SERIALIZER API

97       Here's what POE::Filter::Reference expects of its serializers.
98
99   thaw SERIALIZED
100       thaw() is required.  It accepts two parameters: $self and a scalar
101       containing a SERIALIZED byte stream representing a single Perl data
102       structure.  It returns a reconstituted Perl data structure.
103
104         sub thaw {
105           my ($self, $stream) = @_;
106           my $reference = $self->_deserialization_magic($stream);
107           return $reference;
108         }
109
110   nfreeze REFERENCE
111       Either nfreeze() or freeze() is required.  They behave identically,
112       except that nfreeze() is guaranteed to be portable across networks and
113       between machine architectures.
114
115       These freezers accept two parameters: $self and a REFERENCE to Perl
116       data.  They return a serialized version of the REFERENCEd data.
117
118         sub nfreeze {
119           my ($self, $reference) = @_;
120           my $stream = $self->_serialization_magic($reference);
121           return $stream;
122         }
123
124   freeze REFERENCE
125       freeze() is an alternative form of nfreeze().  It has the same call
126       signature as nfreeze(), but it doesn't guarantee that serialized data
127       will be portable across machine architectures.
128
129       If you must choose between implementing freeze() and nfreeze() for use
130       with POE::Filter::Reference, go with nfreeze().
131

BUGS

139       Not so much bugs as caveats:
140
141       It's important to use identical serializers on each end of a
142       connection.  Even different versions of the same serializer can break
143       data in transit.
144
145       Most (if not all) serializers will re-bless data at the destination,
146       but many of them will not load the necessary classes to make their
147       blessings work.
148

AUTHORS & COPYRIGHTS

150       The Reference filter was contributed by Artur Bergman, with changes by
151       Philip Gwyn.
152
153       Please see POE for more information about authors and contributors.
154
155
156
157perl v5.12.1                      2010-04-03         POE::Filter::Reference(3)