1POE::Filter::Reference(U3s)er Contributed Perl DocumentatPiOoEn::Filter::Reference(3)
2
6 POE::Filter::Reference - freeze and thaw arbitrary Perl data
7
9 #!perl
10 use YAML;
12 use POE qw(Wheel::ReadWrite Filter::Reference);
13 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 $_[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 POE::Kernel->run();
38 exit;
39
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 By default, POE::Filter::Reference uses Storable to do its magic. A
48 different serializer may be specified at construction time.
49
51 new
52 new() creates and initializes a POE::Filter::Reference object. It
53 accepts a list of named parameters.
54 Serializer
56 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 Serializer may be a class name:
62 # Use Storable explicitly, specified by package name.
64 my $filter = POE::Filter::Reference->newer( Serializer=>"Storable" );
65 # Use YAML instead. Compress its output, as it may be verbose.
67 my $filter = POE::Filter::Reference->new("YAML", 1);
68 Serializer may also be an object:
70 # Use an object.
72 my $serializer = Data::Serializer::Something->new();
73 my $filter = POE::Filter::Reference->newer( Serializer => $serializer );
74 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 Compression
81 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 MaxBuffer
87 "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 NoFatals
92 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 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 new() will try to load any classes it needs for "Compression" or
111 "Serializer".
112 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 Calling "new" like this is equivalent to
119 POE::Filter::Reference->new( Serializer => SERIALIZER,
121 Compression => COMPRESSION,
122 NoFatals => NO_FATALS );
123 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
128 Here's what POE::Filter::Reference expects of its serializers.
129 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 sub thaw {
136 my ($self, $stream) = @_;
137 my $reference = $self->_deserialization_magic($stream);
138 return $reference;
139 }
140 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 These freezers accept two parameters: $self and a REFERENCE to Perl
147 data. They return a serialized version of the REFERENCEd data.
148 sub nfreeze {
150 my ($self, $reference) = @_;
151 my $stream = $self->_serialization_magic($reference);
152 return $stream;
153 }
154 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 If you must choose between implementing freeze() and nfreeze() for use
161 with POE::Filter::Reference, go with nfreeze().
162
164 Please see POE::Filter for documentation regarding the base interface.
165 The SEE ALSO section in POE contains a table of contents covering the
167 entire POE distribution.
168
170 Not so much bugs as caveats:
171 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 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
182 The Reference filter was contributed by Artur Bergman, with changes by
183 Philip Gwyn.
184 Please see POE for more information about authors and contributors.
186perl v5.36.0 2023-01-20 POE::Filter::Reference(3)