1POE::Wheel::ReadWrite(3U)ser Contributed Perl DocumentatiPoOnE::Wheel::ReadWrite(3)
2
6 POE::Wheel::ReadWrite - buffered non-blocking I/O
7
9 $wheel = POE::Wheel::ReadWrite->new(
10 # To read and write from the same handle, such as a socket, use
12 # the Handle parameter:
13 Handle => $file_or_socket_handle, # Handle to read/write
14 # To read and write from different handles, such as a dual pipe to
16 # a child process, or a console, use InputHandle and OutputHandle:
17 InputHandle => $readable_filehandle, # Handle to read
18 OutputHandle => $writable_filehandle, # Handle to write
19 Driver => POE::Driver::Something->new(), # How to read/write it
21 # To read and write using the same line discipline, such as
23 # Filter::Line, use the Filter parameter:
24 Filter => POE::Filter::Something->new(), # How to parse in and out
25 # To read and write using different line disciplines, such as
27 # stream out and line in:
28 InputFilter => POE::Filter::Something->new(), # Read data one way
29 OutputFilter => POE::Filter::SomethingElse->new(), # Write data another
30 InputEvent => $input_event_name, # Input received event
32 FlushedEvent => $flush_event_name, # Output flushed event
33 ErrorEvent => $error_event_name, # Error occurred event
34 # To enable callbacks for high and low water events (using any one
36 # of these options requires the rest):
37 HighMark => $high_mark_octets, # Outgoing high-water mark
38 HighEvent => $high_mark_event, # Event to emit when high-water reached
39 LowMark => $low_mark_octets, # Outgoing low-water mark
40 LowEvent => $low_mark_event, # Event to emit when low-water reached
41 );
42 $wheel->put( $something );
44 $wheel->event( ... );
45 # To set both the input and output filters at once:
47 $wheel->set_filter( POE::Filter::Something->new() );
48 # To set an input filter or an output filter:
50 $wheel->set_input_filter( POE::Filter::Something->new() );
51 $wheel->set_output_filter( POE::Filter::Something->new() );
52 # To alter the high or low water marks:
54 $wheel->set_high_mark( $new_high_mark_octets );
55 $wheel->set_low_mark( $new_low_mark_octets );
56 # To fetch driver statistics:
58 $pending_octets = $wheel->get_driver_out_octets();
59 $pending_messages = $wheel->get_driver_out_messages();
60 # To retrieve the wheel's ID:
62 print $wheel->ID;
63 # To pause and resume a wheel's input events.
65 $wheel->pause_input();
66 $wheel->resume_input();
67 # To shutdown a wheel's socket(s).
69 $wheel->shutdown_input();
70 $wheel->shutdown_output();
71
73 ReadWrite performs buffered, select-based I/O on filehandles. It gen‐
74 erates events for common file conditions, such as when data has been
75 read or flushed.
76
78 new new() creates a new wheel, returning the wheels reference.
79
81 put RECORDS
82 put() queues one or more RECORDS for transmission. Each record is of
83 a form dictated by POE::Wheel::ReadWrite's current output filter.
84 ReadWrite uses its output filter to translate the records into a form
85 suitable for writing to a stream. It uses the currently configured
86 driver to buffer and send them.
87 put() accepts a list of records. If a high water mark has been set,
89 it returns a Boolean value indicating whether the driver's output
90 buffer has reached that level. It always returns false if a high
91 water mark has not been set.
92 This example will quickly fill a wheel's output queue if it has a
94 high water mark set. Otherwise it will loop infinitely, eventually
95 exhausting memory and crashing.
96 1 while $wheel->put( get_next_thing_to_send() );
98 event EVENT_TYPE => EVENT_NAME, ...
100 event() is covered in the POE::Wheel manpage.
101 set_filter POE_FILTER
103 set_input_filter POE_FILTER
104 set_output_filter POE_FILTER
105 set_input_filter() changes the filter a wheel uses for reading.
106 set_output_filter() changes a wheel's output filter. set_filter()
107 changes them both at once.
108 These methods let programs change a wheel's underlying protocol while
110 it runs. It retrieves the existing filter's unprocessed input using
111 its get_pending() method and passes that to the new filter.
112 Switching filters can be tricky. Please see the discussion of
114 get_pending() in POE::Filter.
115 The HTTPD filter does not support get_pending(), and it will complain
117 if a program tries to switch away from one.
118 get_input_filter
120 get_output_filter
121 Return the wheel's input or output filter. In many cases, they both
122 may be the same. This is used to access custom methods on the filter
123 itself; for example, Filter::Stackable has methods to push and pop
124 filters on its stack.
125 $wheel->get_input_filter()->pop();
127 set_high_mark HIGH_MARK_OCTETS
129 set_low_mark LOW_MARK_OCTETS
130 These methods set a wheel's high- and low-water marks. New values
131 will not take effect until the next put() call or internal buffer
132 flush. The event() method can change the events emitted by high- and
133 low-water marks.
134 ID
136 The ID method returns a ReadWrite wheel's unique ID. This ID will be
137 included in every event the wheel generates, and it can be used to
138 match events with the wheels which generated them.
139 pause_input
141 resume_input
142 ReadWrite wheels will continually generate input events for as long
143 as they have data to read. Sometimes it's necessary to control the
144 flow of data coming from a wheel or the input filehandle it manages.
145 pause_input() instructs the wheel to temporarily stop checking its
147 input filehandle for data. This can keep a session (or a correspond‐
148 ing output buffer) from being overwhelmed.
149 resume_input() instructs the wheel to resume checking its input file‐
151 handle for data.
152 shutdown_input
154 shutdown_output
155 Some applications require the remote end to shut down a socket before
156 they will continue. These methods map directly to shutdown() for the
157 wheel's input and output sockets.
158 get_driver_out_octets
160 get_driver_out_messages
161 Return driver statistics.
162
164 Driver
165 Driver is a POE::Driver subclass that is used to read from and write
166 to ReadWrite's filehandle(s). It encapsulates the low-level I/O
167 operations so in theory ReadWrite never needs to know about them.
168 Driver defaults to "<POE::Driver::SysRW-"new()>>.
170 Filter
172 Filter is a POE::Filter subclass that's used to parse incoming data
173 and create streamable outgoing data. It encapsulates the lowest
174 level of a protocol so in theory ReadWrite never needs to know about
175 them.
176 Filter defaults to "<POE::Filter::Line-"new()>>.
178 InputEvent
180 InputEvent contains the event that the wheel emits for every complete
181 record read. Every InputEvent is accompanied by two parameters.
182 "ARG0" contains the record which was read. "ARG1" contains the
183 wheel's unique ID.
184 The wheel will not attempt to read from its Handle or InputHandle if
186 InputEvent is omitted.
187 A sample InputEvent handler:
189 sub input_state {
191 my ($heap, $input, $wheel_id) = @_[HEAP, ARG0, ARG1];
192 print "Echoing input from wheel $wheel_id: $input\n";
193 $heap->{wheel}->put($input); # Echo it back.
194 }
195 FlushedEvent
197 FlushedEvent contains the event that ReadWrite emits whenever its
198 output queue becomes empty. This signals that all pending data has
199 been written, and it's often used to wait for "goodbye" messages to
200 be sent before a session shuts down.
201 FlushedEvent comes with a single parameter, "ARG0", that indicates
203 which wheel flushed its buffer.
204 A sample FlushedEvent handler:
206 sub flushed_state {
208 # Stop a wheel after all outgoing data is flushed.
209 # This frees the wheel's resources, including the
210 # filehandle, and closes the connection.
211 delete $_[HEAP]->{wheel}->{$_[ARG0]};
212 }
213 ErrorEvent
215 ErrorEvent contains the event that ReadWrite emits whenever an error
216 occurs. Every ErrorEvent comes with four parameters:
217 "ARG0" contains the name of the operation that failed. This usually
219 is 'read'. Note: This is not necessarily a function name. The wheel
220 doesn't know which function its Driver is using.
221 "ARG1" and "ARG2" hold numeric and string values for $!, respec‐
223 tively.
224 "ARG3" contains the wheel's unique ID.
226 A sample ErrorEvent handler:
228 sub error_state {
230 my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
231 warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
232 delete $heap->{wheels}->{$wheel_id}; # shut down that wheel
233 }
234 HighEvent
236 LowEvent
237 ReadWrite emits a HighEvent when a wheel's pending output queue has
238 grown to be at least HighMark octets. A LowEvent is emitted when a
239 wheel's pending octet count drops below the value of LowMark.
240 HighEvent and LowEvent flip-flop. Once a HighEvent has been emitted,
242 it won't be emitted again until a LowEvent is emitted. Likewise,
243 LowEvent will not be emitted again until HighEvent is. ReadWrite
244 always starts in a low-water state.
245 Sessions which stream output are encouraged to use these events for
247 flow control. Sessions can reduce their transmission rates or stop
248 transmitting altogether upon receipt of a HighEvent, and they can
249 resume full-speed transmission once LowEvent arrives.
250
252 POE::Wheel.
253 The SEE ALSO section in POE contains a table of contents covering the
255 entire POE distribution.
256
258 Oh, probably some.
259
261 Please see POE for more information about authors and contributors.
262perl v5.8.8 2006-09-01 POE::Wheel::ReadWrite(3)