NAME

POE::Wheel::ReadWrite - POE Read/Write Logic Abstraction

SUPPORTED PLATFORMS

Linux
Solaris
Windows

This module is not included with the standard ActivePerl distribution. It is available as a separate download using PPM.

SYNOPSIS

  $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
    Filter       => new POE::Filter::Something(), # How to parse it
    InputState   => $input_state_name,  # Input received state
    FlushedState => $flush_state_name,  # Output flushed state
    ErrorState   => $error_state_name,  # Error occurred state
  );

  $wheel->put( $something );
  $wheel->event( ... );
  $wheel->set_filter( new POE::Filter::Something );

DESCRIPTION

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.

PUBLIC METHODS

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.
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 uses filters' get_pending() method to preserve any buffered data 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.

EVENTS AND PARAMETERS

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";
  }
```

BUGS

Oh, probably some.

AUTHORS & COPYRIGHTS

Please see the POE manpage.

POE::Wheel::ReadWrite - POE Read/Write Logic Abstraction