1POE::Filter(3) User Contributed Perl Documentation POE::Filter(3)
2
6 POE::Filter - a protocol abstraction
7
9 $filter = POE::Filter::Something->new();
10 $arrayref_of_logical_chunks =
11 $filter->get($arrayref_of_raw_chunks_from_driver);
12 $arrayref_of_streamable_chunks_for_driver =
13 $filter->put($arrayref_of_logical_chunks);
14
16 Filters implement generic interfaces to low- and medium-level proto‐
17 cols. Wheels use them to communicate in basic ways without needing to
18 know the details for doing so. For example, the Line filter does
19 everything needed to translate incoming streams into lines and outgoing
20 lines into streams. Sessions can get on with the business of using
21 lines.
22
24 These methods are the generic Filter interface, and every filter must
25 implement them or inherit them from this base class. Specific filters
26 may have additional methods.
27 new
29 new() creates and initializes a new filter. Specific filters may
30 have different constructor parameters.
31 get ARRAYREF
33 get() translates raw data into records. What sort of records is
34 defined by the specific filter. The method accepts a reference to an
35 array of raw data chunks, and it returns a reference to an array of
36 complete records. The returned ARRAYREF will be empty if there
37 wasn't enough information to create a complete record. Partial
38 records may be buffered until subsequent get() calls complete them.
39 my $records = $filter->get( $driver->get( $filehandle ) );
41 get() processes and returns as many records as possible. This is
43 faster than one record per call, but it introduces race conditions
44 when switching filters. If you design filters and intend them to be
45 switchable, please see get_one_start() and get_one().
46 get_one_start ARRAYREF
48 get_one
49 These methods are a second interface to a filter's input translation.
50 They split the usual get() into two stages.
51 get_one_start() accepts an array reference containing unprocessed
53 stream chunks. It adds them to the filter's internal buffer and does
54 nothing else.
55 get_one() takes no parameters and returns an ARRAYREF of zero or more
57 complete records from the filter's buffer. Unlike the plain get()
58 method, get_one() is not greedy. It returns as few records as possi‐
59 ble, preferably just zero or one.
60 get_one_start() and get_one() reduce or eliminate race conditions
62 when switching filters in a wheel.
63 put ARRAYREF
65 put() serializes records into a form that may be written to a file or
66 sent across a socket. It accepts a reference to a list of records,
67 and it returns a reference to a list of stream chunks.
68 The list reference it returns may be passed directly to a driver.
70 $driver->put( $filter->put( \@records ) );
72 get_pending
74 get_pending() returns a filter's partial input buffer. Unlike previ‐
75 ous versions, the filter's input buffer is not cleared. The Read‐
76 Write wheel uses this for hot-swapping filters; it gives partial
77 input buffers to the next filter.
78 get_pending() returns undef if nothing is pending. This is different
80 from get() and get_one().
81 Filters don't have output buffers. They accept complete records and
83 immediately pass the serialized information to a driver's queue.
84 It can be tricky keeping both ends of a socket synchronized during a
86 filter change. It's recommended that some sort of handshake protocol
87 be used to make sure both ends are using the same type of filter at
88 the same time.
89 TCP also tries to combine small packets for efficiency's sake. In a
91 streaming protocol, a filter change could be embedded between two
92 data chunks.
93 type-1 data
95 type-1 data
96 change to type-2 filter
97 type-2 data
98 type-2 data
99 A driver can easily read that as a single chunk. It will be passed
101 to a filter as a single chunk, and that filter (type-1 in the exam‐
102 ple) will break the chunk into pieces. The type-2 data will be
103 interpreted as type-1 because the ReadWrite wheel hasn't had a chance
104 to switch filters yet.
105 Adding a handshake protocol means the sender will wait until a filter
107 change has been acknowledged before going ahead and sending data in
108 the new format.
109 clone
111 clone() makes a copy of the filter, and clears the copy's buffer.
112 3rd party modules can either implement their own clone() or inherit
114 from POE::Filter. If inheriting, the object MUST be an array-ref AND
115 the first element must be the buffer. The buffer can be either a
116 string or an array-ref.
117
119 The SEE ALSO section in POE contains a table of contents covering the
120 entire POE distribution.
121
123 In theory, filters should be interchangeable. In practice, stream and
124 block protocols tend to be incompatible.
125
127 Please see POE for more information about authors and contributors.
128perl v5.8.8 2006-09-01 POE::Filter(3)