| POE::Wheel::FollowTail - follow the tail of an ever-growing file |
POE::Wheel::FollowTail - follow the tail of an ever-growing file
$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
Seek => $offset, # How far from BOF 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
Seek => $offset, # How far from BOF to start
);
$pos = $wheel->tell(); # Get the current log position.
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.
new() creates a new wheel, returning the wheels reference.
event() is covered in the POE::Wheel manpage.
FollowTail's event types are InputEvent, ResetEvent, and
ErrorEvent.
tell() may be useful for seeking back into a file when resuming
tailing.
my $pos = $wheel->tell();
FollowTail generally reads ahead of the data it returns, so the file position is not necessarily the point after the last record you have received.
POE::Wheel::FollowTail uses POE::Driver::SysRW if one is not specified.
POE::Wheel::FollowTail uses POE::Filter::Line if one is not specified.
A Seek parameter of 0 starts FollowTail at the beginning of the file. A negative Seek parameter emulates SeekBack: it seeks backwards from the end of the file.
Seek and SeekBack are mutually exclusive. If Seek and SeekBack are not specified, FollowTail seeks 4096 bytes back from the end of the file and discards everything until the end of the file. This helps ensure that FollowTail returns only complete records.
When either Seek or SeekBack is specified, FollowTail begins returning records from that position in the file. It is possible that the first record returned may be incomplete. In files with fixed-length records, it's possible to return entirely the wrong thing, all the time. Please be careful.
A SeekBack parameter of 0 starts FollowTail at the end of the file. It's recommended to omit Seek and SeekBack to start from the end of a file.
A negative SeekBack parameter emulates Seek: it seeks forwards from the start of the file.
Seek and SeekBack are mutually exclusive. If Seek and SeekBack are not specified, FollowTail seeks 4096 bytes back from the end of the file and discards everything until the end of the file. This helps ensure that FollowTail returns only complete records.
When either Seek or SeekBack is specified, FollowTail begins returning records from that position in the file. It is possible that the first record returned may be incomplete. In files with fixed-length records, it's possible to return entirely the wrong thing, all the time. Please be careful.
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. The named file does not need to exist. FollowTail will wait for it to appear.
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.
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";
}
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.
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";
}
POE::Wheel.
The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.
This wheel can't tail pipes and consoles on some systems.
Please see POE for more information about authors and contributors.
| POE::Wheel::FollowTail - follow the tail of an ever-growing file |