POE::Filter::Reference(3pm)

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

NAME

6       POE::Filter::Reference - freeze data for sending; thaw data when it
7       arrives
8

SYNOPSIS

10         $filter = POE::Filter::Reference->new();
11         $arrayref_of_perl_references =
12           $filter->get($arrayref_of_raw_chunks_from_driver);
13         $arrayref_of_serialized_perl_references =
14            $filter->put($arrayref_of_perl_references);
15

DESCRIPTION

17       This filter packages referenced data for writing to a file or socket.
18       Upon receipt of packaged data, it reconstitutes the original structure
19       and returns a reference to it.  This provides a handy way to ship data
20       between processes and systems.
21

PUBLIC FILTER METHODS

23       new SERIALIZER, COMPRESSION
24       new SERIALIZER
25       new
26         new() creates and initializes a reference filter.  It accepts two
27         optional parameters: A serializer and a flag that determines whether
28         Compress::Zlib will be used to compress serialized data.
29
30         Serializers are modeled after Storable.  Storable has a nfreeze()
31         function which translates referenced data into strings suitable for
32         shipping across sockets.  It also contains a freeze() method which is
33         less desirable since it doesn't take network byte ordering into
34         effect.  Finally there's thaw() which translates frozen strings back
35         into data.
36
37         SERIALIZER may be a package name or an object reference, or it may be
38         omitted altogether.
39
40         If SERIALIZER is a package name, it is assumed that the package will
41         have a thaw() function as well as either an nfreeze() or a freeze()
42         function.
43
44           # Use Storable explicitly, specified by package name.
45           my $filter = POE::Filter::Reference->new("Storable");
46
47           # Use YAML, perhaps to pass data to programs not written with POE or
48           # even in Perl at all.
49           my $filter = POE::Filter::Reference->new("YAML");
50
51         If SERIALIZER is an object reference, it's assumed to have a thaw()
52         method as well as either an nfreeze() or freeze() method.
53
54           # Use an object.
55           my $filter = POE::Filter::Reference->new($object);
56
57         If SERIALIZER is omitted or undef, the Reference filter will try to
58         use Storable, FreezeThaw, and YAML.  Filter::Reference will die if it
59         cannot find one of these serializers.
60
61           # Use the default filter (either Storable, FreezeThaw, or YAML).
62           my $filter = POE::Filter::Reference->new();
63
64         Filter::Reference will try to compress frozen strings and uncompress
65         them before thawing if COMPRESSION is true.  It uses Compress::Zlib
66         for this, but it works fine even without Zlib as long as COMPRESSION
67         is false.
68
69         An object serializer must have a thaw() method.  It also must have
70         either a freeze() or nfreeze() method.  If it has both freeze() and
71         nfreeze(), then Filter::Reference will use nfreeze() for portability.
72         The thaw() method accepts $self and a scalar; it should return a ref‐
73         erence to the reconstituted data.  The freeze() and nfreeze() methods
74         receive $self and a reference; they should return a scalar with the
75         reference's serialized representation.
76
77         If the serializer parameter is undef, a default one will be used.
78         This lets programs specify compression without having to worry about
79         naming a serializer.
80
81         For example:
82
83           # Use the default filter (either Storable, FreezeThaw, or YAML).
84           my $filter = POE::Filter::Reference->new();
85
86           # Use an object, with compression.
87           my $filter = POE::Filter::Reference->new($object, 1);
88
89           # Use the default serializer, with compression.
90           my $filter = POE::Filter::Reference->new(undef, 1);
91
92         The new() method will try to require any packages it needs.
93
94         The default behavior is to try Storable first, FreezeThaw second,
95         YAML third, and finally fail.
96
97       get [ FROZEN_DATA ]
98         The get() method thaws a referenced list of FROZEN_DATA chunks back
99         into references.  References will be blessed, if necessary.  If the
100         references points to an object, be sure the receiving end has used
101         the appropriate modules before calling their methods.
102
103           $thingrefs = $filter_reference->get(\@stream_chunks);
104           foreach (@$thingrefs) {
105             ...;
106           }
107
108       put [ REFERENCES ]
109         The put() method freezes one or more REFERENCES and returns their
110         serialized, streamable representations as a list reference.
111
112           $arrayref = $filter_reference->put([ \%thing_one, \@thing_two ]);
113           foreach (@$arrayref) {
114             ...;
115           }
116

BUGS

124       Whatever is used to freeze and thaw data should be aware of potential
125       differences in system byte orders.  Also be careful that the same
126       freeze/thaw code is used on both sides of a socket.  That includes even
127       the most minor version differences.
128

AUTHORS & COPYRIGHTS

130       The Reference filter was contributed by Arturn Bergman, with changes by
131       Philip Gwyn.
132
133       Please see POE for more information about authors and contributors.
134
135
136
137perl v5.8.8                       2006-09-01         POE::Filter::Reference(3)

NAME

SYNOPSIS

DESCRIPTION

PUBLIC FILTER METHODS

SEE ALSO

BUGS

AUTHORS & COPYRIGHTS