| POE::Wheel::ReadWrite - buffered non-blocking I/O |
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
InputEvent => $input_event_name, # Input received event
FlushedEvent => $flush_event_name, # Output flushed event
ErrorEvent => $error_event_name, # Error occurred event
# 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
HighEvent => $high_mark_event, # Event to emit when high-water reached
LowMark => $low_mark_octets, # Outgoing low-water mark
LowEvent => $low_mark_event, # Event to emit 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;
# To pause and resume a wheel's input events. $wheel->pause_input(); $wheel->resume_input();
# To shutdown a wheel's socket(s). $wheel->shutdown_input(); $wheel->shutdown_output();
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 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 the POE::Filter manpage.
The HTTPD filter does not support get_pending(), and it will complain if a program tries to switch away from one.
$wheel->get_input_filter()->pop();
put() call or internal buffer
flush. The event() method can change the events emitted by high- and
low-water marks.
pause_input() instructs the wheel to temporarily stop checking its
input filehandle for data. This can keep a session (or a
corresponding output buffer) from being overwhelmed.
resume_input() instructs the wheel to resume checking its input
filehandle for data.
shutdown() for the
wheel's input and output sockets.
Driver defaults to <POE::Driver::SysRW-new()>>.
Filter defaults to <POE::Filter::Line-new()>>.
ARG0 contains the record which was read. ARG1 contains the
wheel's unique ID.
The wheel will not attempt to read from its Handle or InputHandle if InputEvent is omitted.
A sample InputEvent 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.
}
FlushedEvent comes with a single parameter, ARG0, that indicates
which wheel flushed its buffer.
A sample FlushedEvent 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]};
}
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.
ARG3 contains the wheel's unique ID.
A sample ErrorEvent 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
}
HighEvent and LowEvent flip-flop. Once a HighEvent has been emitted, it won't be emitted again until a LowEvent is emitted. Likewise, LowEvent will not be emitted again until HighEvent is. ReadWrite always starts in a low-water state.
Sessions which stream output are encouraged to use these events for flow control. Sessions can reduce their transmission rates or stop transmitting altogether upon receipt of a HighEvent, and they can resume full-speed transmission once LowEvent 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.
| POE::Wheel::ReadWrite - buffered non-blocking I/O |