NAME

  Event::File::tail - 'an tail [CB]<-f>' implementation using Event

SYNOPSIS

  use Event::File;
  Event::File->tail(
                    file => '/var/log/messages',
                    cb   => \&my_read_callback_function
                   );
  Event::loop;

DESCRIPTION

Event::FileTail is an attempt to reproduce the behaviour of the 'tail -f' using Event as the backend.

The main difference between this module and other modules that tries to implement it is that it leaves room for parallel processing using Event.

Supported attributes

file

file gives the file name to watch, with either a absolute or relative path. The file has to exist during initialization. After it, it can be unlinked and recreated.

position

where to start reading from the file, in bytes. As the file is read, it will be updated with the last position read.

footprint

footprint, if defined, ia an array reference of n elements. Each element correspond to a line from the beggining of the file. If any line does not match in the file, position will be ignored and started in the beggining.

cb

cb is the standard callback. It will receive a code reference that will be called after every line read from the file. The newline from the line will be chomped before passed. The Event::File::tail object will be passed as the first argument. The read line will be passed as the second argument.

timeout

A timeout starts to calculate after the file read gets to the end. If a new line is added to the file the timer count is reseted. Its main use is to catch a situation when the file is rotated and it was not catched. The file will be closed and reopened. If the file stills the same it will continue from the place it was before closing it. If the file has really changed, it will start reading it from the beggining. If not specified it defaults to 60s.

timeout_cb

This is the callback to call when a timeout occur. The timeout callback will be only called if the reopened file results in the same file.

endfile_cb

This callback will be called every time when the file read gets to the end. So if you need to do something after reading the file (instead of during each read line).

desc

Description of the watcher.

METHODS

This are the methods available for use with the tail watcher.

$watcher->desc;

Returns the description of the watcher.

$watcher->id;

Returns the internal watcher id number.

$position = $watcher->position;

Returns the current file position

$array_ref = $watcher->footprint;

This will return an array reference of the file's footprint. This is handy if you need to quit your application and after restarting it the file can be checked whether it is the same or not.

$result = $watcher->loop($timeout);

loop is a wrapper to Event::loop in case that no other Event's watcher is in use. You have to call it somewhere to let Event watch the file for you. $result will return from the $result value passed by an unloop method (see below). Please refer to the loop function in the Event pod page for more info.

$watcher->unloop($result);

A wrapper to Event::unloop. This will cancel an active Event::loop, e.g. when called from a callback. $result will be passed to the loop caller. Please refer to Event::unloop for more info.

$watcher->sweep;

A wrapper around Event::sweep. sweep will call any event pending and return. Please refer to Event::sweep for mor info.

$watcher->stop;

This will stop the watcher until a again or start method is called.

$watcher->start;

This method will restart the watcher

$watcher->again;

The same as start

$watcher->cancel

This will destroy the watcher. Note that if t there is a reference to this watcher outside this package, the memory won't be freed.

loop vs sweep

When do you have to use loop or sweep?

Well, that depends. If you are not familiar with Event, the quick and dirty answer is loop will BLOCK and sweep no.

loop will be keeping calling the callback functions whenever they are ready and will just return when a callback calls for unloop or a timeout happens.

On the other hand, if you are not using Event for anything else in your program, this might not be a desired situation. sweep can be called them to check if some event has happened or not. If it has it will execute all the pending callbacks and then return (as opposed from loop). So, long loops might be a good place to use it.

IMPLEMENTATION

Event::File::tail is a fake watcher in the Event point of view. On the other hand, it does use two helper watchers for each Event::File::tail, a read io and a timer watchers. In case you are debugging and need to findout about them, every tail watcher has an unique id during the program execution (use $watcher-id) to retrive it). Each helper watcher does have the id number on its description (desc).

SEE ALSO

Event(3), Tutorial.pdf, cmc

AUTHOR

Raul Dias <raul@dias.com.br>

cpanm Event::File

perl -MCPAN -e shell
install Event::File