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   new
52       new() creates and initializes a POE::Filter::Reference object.  It
53       accepts a list of named parameters.
54
55       Serializer
56
57       Any class that supports nfreeze() (or freeze()) and thaw() may be used
58       as a Serializer.  If a Serializer implements both nfreeze() and
59       freeze(), then the "network" (nfreeze) version will be used.
60
61       Serializer may be a class name:
62
63         # Use Storable explicitly, specified by package name.
64         my $filter = POE::Filter::Reference->newer( Serializer=>"Storable" );
65
66         # Use YAML instead.  Compress its output, as it may be verbose.
67         my $filter = POE::Filter::Reference->new("YAML", 1);
68
69       Serializer may also be an object:
70
71         # Use an object.
72         my $serializer = Data::Serializer::Something->new();
73         my $filter = POE::Filter::Reference->newer( Serializer => $serializer );
74
75       If Serializer is omitted or undef, the Reference filter will try to use
76       Storable, FreezeThaw, and YAML in that order.  POE::Filter::Reference
77       will die if it cannot find one of these serializers, but this rarely
78       happens now that Storable and YAML are bundled with Perl.
79
80       Compression
81
82       If Compression is true, Compress::Zlib will be called upon to reduce
83       the size of serialized data.  It will also decompress the incoming
84       stream data.
85
86       MaxBuffer
87
88       "MaxBuffer" sets the maximum amount of data that the filter will hold
89       onto while trying to build a new reference.  Defaults to 512 MB.
90
91       NoFatals
92
93       If NoFatals is true, messages will be thawed inside a block eval.  By
94       default, however, thaw() is allowed to die normally.  If an error
95       occurs while NoFatals is in effect, POE::Filter::Reference will return
96       a string containing the contents of $@ at the time the eval failed.  So
97       when using NoFatals, it's important to check whether input is really a
98       reference:
99
100         sub got_reference {
101           my $message = $_[ARG0];
102           if (ref $message) {
103             print "Got data:\n", YAML::Dump($message);
104           }
105           else {
106             warn "Input decode error: $message\n";
107           }
108         }
109
110       new() will try to load any classes it needs for "Compression" or
111       "Serializer".
112
113   new [SERIALIZER [, COMPRESSION [, NO_FATALS]]]
114       This is the old constructor synatx.  It does not conform to the normal
115       POE::Filter constructor parameter syntax.  Please use the new syntax
116       instead.
117
118       Calling "new" like this is equivalent to
119
120           POE::Filter::Reference->new( Serializer => SERIALIZER,
121                                        Compression => COMPRESSION,
122                                        NoFatals  => NO_FATALS );
123
124       Please note that if you have a custom serializer class called
125       "Serializer" you will have to update your code to the new syntax.
126

SERIALIZER API

128       Here's what POE::Filter::Reference expects of its serializers.
129
130   thaw SERIALIZED
131       thaw() is required.  It accepts two parameters: $self and a scalar
132       containing a SERIALIZED byte stream representing a single Perl data
133       structure.  It returns a reconstituted Perl data structure.
134
135         sub thaw {
136           my ($self, $stream) = @_;
137           my $reference = $self->_deserialization_magic($stream);
138           return $reference;
139         }
140
141   nfreeze REFERENCE
142       Either nfreeze() or freeze() is required.  They behave identically,
143       except that nfreeze() is guaranteed to be portable across networks and
144       between machine architectures.
145
146       These freezers accept two parameters: $self and a REFERENCE to Perl
147       data.  They return a serialized version of the REFERENCEd data.
148
149         sub nfreeze {
150           my ($self, $reference) = @_;
151           my $stream = $self->_serialization_magic($reference);
152           return $stream;
153         }
154
155   freeze REFERENCE
156       freeze() is an alternative form of nfreeze().  It has the same call
157       signature as nfreeze(), but it doesn't guarantee that serialized data
158       will be portable across machine architectures.
159
160       If you must choose between implementing freeze() and nfreeze() for use
161       with POE::Filter::Reference, go with nfreeze().
162

SEE ALSO

164       Please see POE::Filter for documentation regarding the base interface.
165
166       The SEE ALSO section in POE contains a table of contents covering the
167       entire POE distribution.
168

BUGS

170       Not so much bugs as caveats:
171
172       It's important to use identical serializers on each end of a
173       connection.  Even different versions of the same serializer can break
174       data in transit.
175
176       Most (if not all) serializers will re-bless data at the destination,
177       but many of them will not load the necessary classes to make those
178       blessings work.  Make sure the same classes and versions are available
179       on either end of the wire.
180

AUTHORS & COPYRIGHTS

182       The Reference filter was contributed by Artur Bergman, with changes by
183       Philip Gwyn.
184
185       Please see POE for more information about authors and contributors.
186
187
188
189perl v5.36.0                      2023-01-20         POE::Filter::Reference(3)
Impressum