NAME

POE::Wheel - POE FollowTail Protocol Logic

SYNOPSIS

  $wheel = new POE::Wheel::FollowTail(
    Handle       => $file_handle,                 # File to tail
    Driver       => new POE::Driver::Something(), # How to read it
    Filter       => new POE::Filter::Something(), # How to parse it
    PollInterval => 1,                  # How often to check it
    InputState   => $input_event_name,  # State to call upon input
    ErrorState   => $error_event_name,  # State to call upon error
  );

DESCRIPTION

This wheel follows the end of an ever-growing file, perhaps a log file, and generates events whenever new data appears. It is a read-only wheel, so it does not include a put() method. It uses sysseek(2) wrapped in eval { }, so it should work okay on all sorts of files. That is, if perl supports select(2)'ing them on the underlying operating system.

PUBLIC METHODS

• POE::Wheel::FollowTail::event(...)

  Please see POE::Wheel.

• POE::Wheel::FollowTail::ID()

  Returns the FollowTail wheel's unique ID. This can be used to associate the wheel's events back to the wheel itself.

EVENTS AND PARAMETERS

• PollInterval

  PollInterval is the number of seconds to wait between file checks. Once FollowTail re-reaches the end of the file, it waits this long before checking again.

• SeekBack

  SeekBack is the number of bytes to seek back from the current end of file before reading. By default, this is 4096, and data read up to the end of file is not returned. (This is used to frame lines before returning actual data.) If SeekBack is specified, then existing data up until EOF is returned, and then the wheel begins following tail.

• InputState

  The InputState event is identical to POE::Wheel::ReadWrite's InputState. It's the state to be called when the followed file lengthens.

  ARG0 contains a logical chunk of data, read from the end of the tailed file. ARG1 contains the ID of the wheel that received this input.

• ErrorState

  The ErrorState event contains the name of the state that will be called when a file error occurs. The FollowTail wheel knows what to do with EAGAIN, so it's not considered a true error. FollowTail will continue running even on an error, so it's up to the Session to stop things if that's what it wants.

  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. ARG3 contains the ID of the wheel that encountered the error; this is useful for closing the proper wheel when one of several has encountered an error.

  A sample ErrorState state:

    sub error_state {
      my ($operation, $errnum, $errstr) = @_[ARG0, ARG1, ARG2];
      warn "$operation error $errnum: $errstr\n";
    }

SEE ALSO

POE::Wheel; POE::Wheel::ListenAccept; POE::Wheel::ReadWrite; POE::Wheel::SocketFactory

BUGS

This wheel can't tail pipes and consoles. Blargh.

AUTHORS & COPYRIGHTS

Please see the POE manpage.