On Apache
Under GNU General Public License
2012-05-25 00:27 @38.107.179.240 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
POE::Wheel::ReadWrite(3pm) User Contributed Perl Documentation POE::Wheel::ReadWrite(3pm)
NAME
POE::Wheel::ReadWrite - buffered non-blocking I/O
SYNOPSIS
$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
# Experimental: If true, flush output synchronously during put()
AutoFlush => $boolean,
);
$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();
# Experimental: Flush a wheel's output on command.
$wheel->flush();
DESCRIPTION
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.
CONSTRUCTOR
new new() creates a new wheel, returning the wheels reference.
PUBLIC METHODS
put RECORDS
put() queues one or more RECORDS for transmission. Each record is of a form dictated by
POE::Wheel::ReadWrite's current output filter. ReadWrite uses its output filter to
translate the records into a form suitable for writing to a stream. It uses the
currently configured driver to buffer and send them.
put() accepts a list of records. If a high water mark has been set, it returns a
Boolean value indicating whether the driver's output buffer has reached that level. It
always returns false if a high water mark has not been set.
This example will quickly fill a wheel's output queue if it has a high water mark set.
Otherwise it will loop infinitely, eventually exhausting memory and crashing.
1 while $wheel->put( get_next_thing_to_send() );
event EVENT_TYPE => EVENT_NAME, ...
event() is covered in the POE::Wheel manpage.
set_filter POE_FILTER
set_input_filter POE_FILTER
set_output_filter POE_FILTER
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.
get_input_filter
get_output_filter
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();
set_high_mark HIGH_MARK_OCTETS
set_low_mark LOW_MARK_OCTETS
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.
ID
The ID method returns a ReadWrite 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.
pause_input
resume_input
ReadWrite wheels will continually generate input events for as long as they have data to
read. Sometimes it's necessary to control the flow of data coming from a wheel or the
input filehandle it manages.
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.
get_input_handle
get_output_handle
These methods return the input and output handles (usually the same thing, but sometimes
not). Please use sparingly. Remember odd references will screw with POE's internals.
shutdown_input
shutdown_output
Some applications require the remote end to shut down a socket before they will
continue. These methods map directly to shutdown() for the wheel's input and output
sockets.
get_driver_out_octets
get_driver_out_messages
Return driver statistics.
flush
Though the watermarks affect how often a wheel is flushed, in some cases you might want
to manually flush a smaller output, such as before shutdown_output.
This method is experimental. Its behavior may change or it may disappear outright.
Please let us know whether it's useful.
EVENTS AND PARAMETERS
Driver
Driver is a POE::Driver subclass that is used to read from and write to ReadWrite's
filehandle(s). It encapsulates the low-level I/O operations so in theory ReadWrite
never needs to know about them.
Driver defaults to "<POE::Driver::SysRW-"new()>>.
Filter
Filter is a POE::Filter subclass that's used to parse incoming data and create
streamable outgoing data. It encapsulates the lowest level of a protocol so in theory
ReadWrite never needs to know about them.
Filter defaults to "<POE::Filter::Line-"new()>>.
InputEvent
InputEvent contains the event that the wheel emits for every complete record read.
Every InputEvent is accompanied by two parameters. "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
FlushedEvent 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.
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]};
}
ErrorEvent
ErrorEvent contains the event that ReadWrite emits whenever an error occurs. Every
ErrorEvent 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.
"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
LowEvent
ReadWrite emits a HighEvent when a wheel's pending output queue has grown to be at least
HighMark octets. A LowEvent is emitted when a wheel's pending octet count drops below
the value of LowMark.
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.
SEE ALSO
POE::Wheel.
The SEE ALSO section in POE contains a table of contents covering the entire POE
distribution.
BUGS
Oh, probably some.
AUTHORS & COPYRIGHTS
Please see POE for more information about authors and contributors.
perl v5.10.0 2008-04-15 POE::Wheel::ReadWrite(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-25 00:27 @38.107.179.240 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)