NAME

POE::Wheel::FollowTail - follow the tail of an ever-growing file

SYNOPSIS

  $wheel = POE::Wheel::FollowTail->new(
    Filename     => $file_name,                    # File to tail
    Driver       => POE::Driver::Something->new(), # How to read it
    Filter       => POE::Filter::Something->new(), # How to parse it
    PollInterval => 1,                  # How often to check it
    InputEvent   => $input_event_name,  # Event to emit upon input
    ErrorEvent   => $error_event_name,  # Event to emit upon error
    ResetEvent   => $reset_event_name,  # Event to emit on file reset
    SeekBack     => $offset,            # How far from EOF to start
  );

  $wheel = POE::Wheel::FollowTail->new(
    Handle       => $open_file_handle,             # File to tail
    Driver       => POE::Driver::Something->new(), # How to read it
    Filter       => POE::Filter::Something->new(), # How to parse it
    PollInterval => 1,                  # How often to check it
    InputEvent   => $input_event_name,  # Event to emit upon input
    ErrorEvent   => $error_event_name,  # Event to emit upon error
    # No reset event available.
    SeekBack     => $offset,            # How far from EOF to start
  );

DESCRIPTION

FollowTail follows the end of an ever-growing file, such as a log of system events. It generates events for each new record that is appended to its file.

This is a read-only wheel so it does not include a put() method.

PUBLIC METHODS

event EVENT_TYPE => EVENT_NAME, ...

event() is covered in the POE::Wheel manpage.

FollowTail's event types are InputEvent, ResetEvent, and ErrorEvent.

ID

The ID method returns a FollowTail 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.

EVENTS AND PARAMETERS

Driver

Driver is a POE::Driver subclass that is used to read from and write to FollowTail's filehandle. It encapsulates the low-level I/O operations needed to access a file so in theory FollowTail never needs to know about them.

POE::Wheel::FollowTail uses POE::Driver::SysRW if one is not specified.

Filter

Filter is a POE::Filter subclass that is used to parse input from the tailed file. It encapsulates the lowest level of a protocol so that in theory FollowTail never needs to know about file formats.

POE::Wheel::FollowTail uses POE::Filter::Line if one is not specified.

PollInterval

PollInterval is the amount of time, in seconds, the wheel will wait before retrying after it has reached the end of the file. This delay prevents the wheel from going into a CPU-sucking loop.

SeekBack

The SeekBack parameter tells FollowTail how far before EOF to start reading before following the file. Its value is specified in bytes, and values greater than the file's current size will quietly cause FollowTail to start from the file's beginning.

When SeekBack isn't specified, the wheel seeks 4096 bytes before the end of the file and discards everything it reads up until EOF. It does this to frame records within the file.

When SeekBack is used, the wheel assumes that records have already been framed, and the seek position is the beginning of one. It will return everything it reads up until EOF.

Handle

Filename

Either the Handle or Filename constructor parameter is required, but you cannot supply both.

FollowTail can watch a file or device that's already open. Give it the open filehandle with its Handle parameter.

FollowTail can watch a file by name, given as the Filename parameter.

This wheel can detect files that have been "reset". That is, it can tell when log files have been restarted due to a rotation or purge. For FollowTail to do this, though, it requires a Filename parameter. This is so FollowTail can reopen the file after it has reset. See ResetEvent elsewhere in this document.

InputEvent

InputEvent contains the name of an event which is emitted for every complete record read. Every InputEvent event is accompanied by two parameters. ARG0 contains the record which was read. ARG1 contains the wheel's unique ID.

A sample InputEvent event handler:

  sub input_state {
    my ($heap, $input, $wheel_id) = @_[HEAP, ARG0, ARG1];
    print "Wheel $wheel_id received input: $input\n";
  }

ResetEvent

ResetEvent contains the name of an event that's emitted every time a file is reset.

It's only available when watching files by name. This is because FollowTail must reopen the file after it has been reset.

ARG0 contains the FollowTail wheel's unique ID.

ErrorEvent

ErrorEvent contains the event which is emitted 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. Note: FollowTail knows how to handle EAGAIN, so it will never return that error.

ARG3 contains the wheel's unique ID.

A sample ErrorEvent event handler:

  sub error_state {
    my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
    warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
  }

SEE ALSO

POE::Wheel.

The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.

BUGS

This wheel can't tail pipes and consoles on some systems.

Because this wheel is cooperatively multitasked, it may lose records just prior to a file reset. For a more robust way to watch files, consider using POE::Wheel::Run and your operating system's native "tail" utility instead.

  $heap->{tail} = POE::Wheel::Run->new
    ( Program     => [ "/usr/bin/tail", "-f", $file_name ],
      StdoutEvent => "log_record",
    );

AUTHORS & COPYRIGHTS

Please see POE for more information about authors and contributors.