POE::Wheel::ReadWrite - POE Read/Write Logic Abstraction
$wheel = new POE::Wheel::ReadWrite( # 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 => new POE::Driver::Something(), # How to read/write it # To read and write using the same line discipline, such as # Filter::Line, use the Filter parameter: Filter => new POE::Filter::Something(), # How to parse in and out # To read and write using different line disciplines, such as # stream out and line in: InputFilter => new POE::Filter::Something(), # Read data one way OUtputFilter => new POE::Filter::SomethingElse(), # 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( new POE::Filter::Something ); # To set an input filter or an output filter: $wheel->set_input_filter( new POE::Filter::Something ); $wheel->set_output_filter( new POE::Filter::Something ); # 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();
The ReadWrite wheel does buffered, select-based I/O on a filehandle. It generates events for common file conditions, such as when data has been read or flushed. This wheel includes a put() method.
POE::Wheel::ReadWrite::put($logical_data_chunk)
The put() method uses a POE::Filter to translate the logical data chunk into a serialized (streamable) representation. It then uses a POE::Driver to enqueue or write the data to a filehandle. It also manages the wheel's write select so that any buffered data can be flushed when the handle is ready.
The put() method returns a boolean value indicating whether the wheel's high water mark has been reached. It will always return false if the wheel doesn't have a high water mark set.
Data isn't flushed to the underlying filehandle, so it's easy for put() to exceed a wheel's high water mark without generating a HighState event.
POE::Wheel::ReadWrite::event(...)
Please see POE::Wheel.
POE::Wheel::ReadWrite::set_filter( $poe_filter )
The set_filter method changes the filter that the ReadWrite wheel uses to translate between streams and logical chunks of data. It sets both the read and write filters. It uses filters' get_pending() method to preserve any unprocessed input between the previous and new filters.
Please be aware that this method has complex and perhaps non-obvious side effects. The description of POE::Filter::get_pending() discusses them further.
POE::Filter::HTTPD does not support the get_pending() method. Switching from an HTTPD filter to another one will display a reminder that it sn't supported.
POE::Wheel::ReadWrite::set_input_filter( $poe_filter ) POE::Wheel::ReadWrite::set_output_filter( $poe_filter )
These perform similar functions to the &set_filter method, but they change the input or output filters separately.
POE::Wheel::ReadWrite->set_high_mark( $high_mark_octets ) POE::Wheel::ReadWrite->set_low_mark( $low_mark_octets )
Sets the high and low watermark octet counts. They will not take effect until the next $wheel->put() or internal buffer flush. POE::Wheel::ReadWrite->event() can change the high and low watermark events.
InputState
The InputState event contains the name of the state that will be called for each chunk of logical data returned by the ReadWrite wheel's filter.
The ARG0 parameter contains the chunk of logical data that was received.
A sample InputState state:
sub input_state { my ($heap, $input) = @_[HEAP, ARG0]; print "Echoing input: $input\n"; $heap->{wheel}->put($input); # Echo it back. }
FlushedState
The FlushedState event contains the name of the state that will be called whenever the wheel's driver's output queue becomes empty. This signals that all pending data has been written. It does not include parameters.
A sample FlushedState state:
sub flushed_state { # Stop the wheel after all outgoing data is flushed. # This frees the wheel's resources, including the # filehandle, and closes the connection. delete $_[HEAP]->{wheel}; }
ErrorState
The ErrorState event contains the name of the state that will be called when a file error occurs. The ReadWrite wheel knows what to do with EAGAIN, so it's not considered a true error.
The ARG0 parameter contains the name of the function that failed. ARG1 and ARG2 contain the numeric and string versions of $! at the time of the error, respectively.
A sample ErrorState state:
sub error_state { my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2]; warn "$operation error $errnum: $errstr\n"; }
HighState
The HighState event indicates when the wheel's driver's output buffer has grows to reach HighMark octets of unwritten data. This event will fire once when the output buffer reaches HighMark, and it will not fire again until a LowState event occurs.
HighState and LowState together are used for flow control. The idea is to perform some sort of throttling when HighState is called and resume full-speed transmission when LowState is called.
HighState includes no parameters.
LowState
The LowState event indicates when a wheel's driver's output buffer shrinks down to LowMark octets of unwritten data. This event will only fire when the output buffer reaches LowMark after a HighState event.
LowState includes no parameters.
POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept; POE::Wheel::SocketFactory
Oh, probably some.
Please see the POE manpage.
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.