NAME

POE::Wheel::FollowTail - follow the end of a file, notifying a session whenever a complete unit of information appears

SYNOPSIS

$wheel_rw = new POE::Wheel::FollowTail
  ( $kernel,
    'Handle' => $handle,
    'Driver' => new POE::Driver::SysRW,  # or another POE::Driver
    'Filter' => new POE::Filter::Line,   # or another POE::Filter
    'InputState'   => $input_state_name, # accepts filtered-input events
    'ErrorState'   => $error_state_name, # accepts error states
  );

DESCRIPTION

POE::Wheel::FollowTail works much like POE::Wheel::ReadWrite except that FollowTail is a read-only wheel (no 'FlushedState') and it starts from the end of a file.

Every complete chunk of input is passed back to the parent POE::Session as a parameter of an 'InputState' event.

If an error occurs, its number and text are sent to the 'ErrorState'. If no 'ErrorState' is provided, the FollowTail wheel will turn off selects for $handle to prevent extra events from being generated. This may stop the the parent POE::Session if the selects are all it is waiting for.

PUBLIC METHODS

new POE::Wheel::FollowTail

Creates a FollowTail wheel. $kernel is the kernel that owns the currently running session (the session that creates this wheel).

Parameters specific to FollowTail:

'Handle'

This is the IO::Handle derivative that will be read from and written to.

'Driver'

This is the POE::Driver derivative that will do the actual reading and writing.

'Filter'

This is the POE::Filter derivative that will frame input and output for the current POE::Session.

'InputState'

This names the event that will be sent to the current session whenever a fully-framed chunk of data has been read from the 'Handle'.

'InputState' handlers will receive these parameters: $kernel, $namespace, $origin_session, $cooked_input. The first three are standard; the last is a post-POE::Filter chunk of input.

'ErrorState'

This names the event that will receive notification of any errors that occur when 'Driver' is reading or writing.

'ErrorState' handlers will these parameters: $kernel, $namespace, $origin_session, $operation, $errnum, $errstr. The first three are standard; $operation is either 'read' or 'write'; $errnum is ($!+0); $errstr is $!.

PRIVATE METHODS

Not for general use.

DESTROY

Removes POE::Wheel::FollowTail states from the parent POE::Session. Releases owned objects so Perl can GC them.

EXAMPLES

Please see tests/followtail.perl for an example of POE::Wheel::FollowTail.

BUGS

Possible enhancement: Automagically reset the file position when a log shrinks, so whatever is watching it does not need to be restarted.

'Position' constructor parameter, so the "current" file position can be maintained between runs.

CONTACT AND COPYRIGHT

Copyright 1998 Rocco Caputo <troc@netrus.net>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.