| 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.
new() creates a new wheel, returning the wheels reference.
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 |