NAME

POE::Wheel::ReadWrite - glue to connect select(2), a POE::Driver, a POE::Filter and the current POE::Session

SYNOPSIS

$wheel_rw = new POE::Wheel::ReadWrite
  ( $kernel,
    'Handle' => $handle,
    'Driver' => new POE::Driver::SysRW,  # or another POE::Driver
    'Filter' => new POE::Filter::Line,   # or another POE::Filter
    'InputState'   => $input_state_name, # accepts filtered-input events
    'FlushedState' => $flush_state_name, # accepts output-flushed events
    'ErrorState'   => $error_state_name, # accepts error states
  );

DESCRIPTION

POE::Wheel::ReadWrite adds select(2) states to the current POE::Session. These states invoke the associated POE::Driver to frob $handle, then pass the stream info to POE::Filter for formatting. The example in the SYNOPSIS above implements line-based IO.

Every complete chunk of input is passed back to the parent POE::Session as a parameter of an 'InputState' event.

The ReadWrite wheel sends 'FlushedState' events whenever its POE::Driver has written all the pending data to $handle. This is optional.

If an error occurs, its number and text are sent to the 'ErrorState'. If no 'ErrorState' is provided, the ReadWrite wheel will turn off selects for $handle to prevent extra events from being generated. This may stop the the parent POE::Session if the selects are all it is waiting for.

PUBLIC METHODS

new POE::Wheel::ReadWrite

Creates a ReadWrite wheel. $kernel is the kernel that owns the currently running session (the session that creates this wheel).

Parameters specific to ReadWrite:

'Handle'

This is the IO::Handle derivative that will be read from and written to.

'Driver'

This is the POE::Driver derivative that will do the actual reading and writing.

'Filter'

This is the POE::Filter derivative that will frame input and output for the current POE::Session.

'InputState'

This names the event that will be sent to the current session whenever a fully-framed chunk of data has been read from the 'Handle'.

'InputState' handlers will receive these parameters: $kernel, $namespace, $origin_session, $cooked_input. The first three are standard; the last is a post-POE::Filter chunk of input.

'FlushedState'

This names the event that will be sent to the current session whenever all buffered output has been written to 'Handle'.

'FlushedState' handlers will receive these parameters: $kernel, $namespace, $origin_session. See _start for POE::Session for an explication.

'ErrorState'

This names the event that will receive notification of any errors that occur when 'Driver' is reading or writing.

'ErrorState' handlers will these parameters: $kernel, $namespace, $origin_session, $operation, $errnum, $errstr. The first three are standard; $operation is either 'read' or 'write'; $errnum is ($!+0); $errstr is $!.

put ($output)

Have the wheel send a chunk of output.

POE::Wheel::ReadWrite formats $output using its POE::Filter. The formatted output is buffered for writing by the POE::Driver. The ReadWrite wheel then uses $kernel-select(...)> to enable a write state that will flush the output buffer.

POE::Wheel::ReadWrite sends a 'FlushedState' event to the session when all buffered output has been written, and it calls $kernel-select(...)> to disable the previously selected write state.

If any errors occur during reading or writing, they are passed back to the parent POE::Session as an 'ErrorState' event.

PRIVATE METHODS

Not for general use.

DESTROY

Removes POE::Wheel::ReadWrite states from the parent POE::Session. Releases owned objects so Perl can GC them.

EXAMPLES

Please see tests/wheels.perl for an example of POE::Wheel::ReadWrite.

BUGS

None known.

CONTACT AND COPYRIGHT

Copyright 1998 Rocco Caputo <troc@netrus.net>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.