NAME

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

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

    # To read and write using the same line discipline, such as
    # Filter::Line, use the Filter parameter:
    Filter       => new POE::Filter::Something(), # How to parse in and out

    # To read and write using different line disciplines, such as
    # stream out and line in:
    InputFilter  => new POE::Filter::Something(),     # Read data one way
    OUtputFilter => new POE::Filter::SomethingElse(), # Write data another

    InputState   => $input_state_name,  # Input received state
    FlushedState => $flush_state_name,  # Output flushed state
    ErrorState   => $error_state_name,  # Error occurred state

    # 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
    HighState => $high_mark_state,  # State to call when high-water reached
    LowMark   => $low_mark_octets,  # Outgoing low-water mark
    LowState  => $low_mark_state,   # State to call when low-water reached
  );

  $wheel->put( $something );
  $wheel->event( ... );

  # To set both the input and output filters at once:
  $wheel->set_filter( new POE::Filter::Something );

  # To set an input filter or an output filter:
  $wheel->set_input_filter( new POE::Filter::Something );
  $wheel->set_output_filter( new POE::Filter::Something );

  # 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();

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.

  The put() method returns a boolean value indicating whether the wheel's high water mark has been reached. It will always return false if the wheel doesn't have a high water mark set.

  Data isn't flushed to the underlying filehandle, so it's easy for put() to exceed a wheel's high water mark without generating a HighState event.

• 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 sets both the read and write filters. It uses filters' get_pending() method to preserve any unprocessed input 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.

• POE::Wheel::ReadWrite::set_input_filter( $poe_filter ) POE::Wheel::ReadWrite::set_output_filter( $poe_filter )

  These perform similar functions to the &set_filter method, but they change the input or output filters separately.

• POE::Wheel::ReadWrite->set_high_mark( $high_mark_octets ) POE::Wheel::ReadWrite->set_low_mark( $low_mark_octets )

  Sets the high and low watermark octet counts. They will not take effect until the next $wheel->put() or internal buffer flush. POE::Wheel::ReadWrite->event() can change the high and low watermark events.

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

• HighState

  The HighState event indicates when the wheel's driver's output buffer has grows to reach HighMark octets of unwritten data. This event will fire once when the output buffer reaches HighMark, and it will not fire again until a LowState event occurs.

  HighState and LowState together are used for flow control. The idea is to perform some sort of throttling when HighState is called and resume full-speed transmission when LowState is called.

  HighState includes no parameters.

• LowState

  The LowState event indicates when a wheel's driver's output buffer shrinks down to LowMark octets of unwritten data. This event will only fire when the output buffer reaches LowMark after a HighState event.

  HighState and LowState together are used for flow control. The idea is to perform some sort of throttling when HighState is called and resume full-speed transmission when LowState is called.

  LowState includes no parameters.

SEE ALSO

POE::Wheel; POE::Wheel::FollowTail; POE::Wheel::ListenAccept; POE::Wheel::SocketFactory

BUGS

Oh, probably some.

AUTHORS & COPYRIGHTS

Please see the POE manpage.