POE::Wheel::ReadWrite - buffered non-blocking I/O
$wheel = POE::Wheel::ReadWrite->new( # To read and write from the same handle, such as a socket, use # the Handle parameter: Handle => $file_or_socket_handle, # Handle to read/write # To read and write from different handles, such as a dual pipe to # a child process, or a console, use InputHandle and OutputHandle: InputHandle => $readable_filehandle, # Handle to read OutputHandle => $writable_filehandle, # Handle to write Driver => POE::Driver::Something->new(), # How to read/write it # To read and write using the same line discipline, such as # Filter::Line, use the Filter parameter: Filter => POE::Filter::Something->new(), # How to parse in and out # To read and write using different line disciplines, such as # stream out and line in: InputFilter => POE::Filter::Something->new(), # Read data one way OUtputFilter => POE::Filter::SomethingElse->new(), # Write data another InputState => $input_state_name, # Input received state FlushedState => $flush_state_name, # Output flushed state ErrorState => $error_state_name, # Error occurred state # To enable callbacks for high and low water events (using any one # of these options requires the rest): HighMark => $high_mark_octets, # Outgoing high-water mark HighState => $high_mark_state, # State to call when high-water reached LowMark => $low_mark_octets, # Outgoing low-water mark LowState => $low_mark_state, # State to call when low-water reached ); $wheel->put( $something ); $wheel->event( ... ); # To set both the input and output filters at once: $wheel->set_filter( POE::Filter::Something->new() ); # To set an input filter or an output filter: $wheel->set_input_filter( POE::Filter::Something->new() ); $wheel->set_output_filter( POE::Filter::Something->new() ); # To alter the high or low water marks: $wheel->set_high_mark( $new_high_mark_octets ); $wheel->set_low_mark( $new_low_mark_octets ); # To fetch driver statistics: $pending_octets = $wheel->get_driver_out_octets(); $pending_messages = $wheel->get_driver_out_messages(); # To retrieve the wheel's ID: print $wheel->ID;
ReadWrite performs buffered, select-based I/O on filehandles. It generates events for common file conditions, such as when data has been read or flushed.
put() queues records for transmission. They may not be transmitted immediately. ReadWrite uses its Filter to translate the records into a form suitable for writing. It uses its Driver to queue and send them.
put() accepts a reference to a list of records. It returns a boolean value indicating whether the wheel's high-water mark has been reached. It always returns false if a wheel doesn't have a high-water mark set.
This will quickly fill a wheel's output queue if it has a high-water mark set. Otherwise it will loop infinitely, eventually exhausting memory.
1 while $wheel->put( &get_next_thing_to_send );
event() is covered in the POE::Wheel manpage.
set_input_filter() changes the filter a wheel uses for reading. set_output_filter() changes a wheel's output filter. set_filter() changes them both at once.
These methods let programs change a wheel's underlying protocol while it runs. It retrieves the existing filter's unprocessed input using its get_pending() method and passes that to the new filter.
Switching filters can be tricky. Please see the discussion of get_pending() in POE::Filter.
The HTTPD filter does not support get_pending(), and it will complain if a program tries to switch away from one.
Return the wheel's input or output filter. In many cases, they both may be the same. This is used to access custom methods on the filter itself; for example, Filter::Stackable has methods to push and pop filters on its stack.
$wheel->get_input_filter()->pop();
These methods set a wheel's high- and low-water marks. New values will not take effect until the next put() call or internal buffer flush. The event() method can change the events emitted by high- and low-water marks.
The ID method returns a FollowTail wheel's unique ID. This ID will be included in every event the wheel generates, and it can be used to match events with the wheels which generated them.
InputState contains the event that the wheel emits for every complete record read. Every InputState event is accompanied by two parameters. ARG0 contains the record which was read. ARG1 contains the wheel's unique ID.
ARG0
ARG1
A sample InputState event handler:
sub input_state { my ($heap, $input, $wheel_id) = @_[HEAP, ARG0, ARG1]; print "Echoing input from wheel $wheel_id: $input\n"; $heap->{wheel}->put($input); # Echo it back. }
FlushedState contains the event that ReadWrite emits whenever its output queue becomes empty. This signals that all pending data has been written, and it's often used to wait for "goodbye" messages to be sent before a session shuts down.
FlushedState comes with a single parameter, ARG0, that indicates which wheel flushed its buffer.
A sample FlushedState event handler:
sub flushed_state { # Stop a wheel after all outgoing data is flushed. # This frees the wheel's resources, including the # filehandle, and closes the connection. delete $_[HEAP]->{wheel}->{$_[ARG0]}; }
ErrorState contains the event that ReadWrite emits whenever an error occurs. Every ErrorState event comes with four parameters:
ARG0 contains the name of the operation that failed. This usually is 'read'. Note: This is not necessarily a function name. The wheel doesn't know which function its Driver is using.
ARG1 and ARG2 hold numeric and string values for $!, respectively.
ARG2
$!
ARG3 contains the wheel's unique ID.
ARG3
A sample ErrorState event handler:
sub error_state { my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3]; warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n"; delete $heap->{wheels}->{$wheel_id}; # shut down that wheel }
ReadWrite emits a HighState event when a wheel's pending output queue has grown to be at least HighMark octets. A LowState event is emitted when a wheel's pending octet count drops below the value of LowMark.
HighState and LowState flip-flop. Once a HighState event has been fired, it won't be fired again until LowState's event is. Likewise, LowState will not be fired again until HighState is. ReadWrite always starts in a low-water state.
Streaming sessions are encouraged to used these states for flow control. Sessions can reduce their transmission rates or stop transmitting altogether upon receipt of a HighState event. They can resume full-speed transmission once LowState arrives.
POE::Wheel.
The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.
Oh, probably some.
Please see POE for more information about authors and contributors.
To install POE, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE
CPAN shell
perl -MCPAN -e shell install POE
For more information on module installation, please visit the detailed CPAN module installation guide.