home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-perl-addon-1.4.9-installer.exe / FollowTail.pm < prev    next >
Encoding:
Perl POD Document  |  2004-04-20  |  21.8 KB  |  689 lines
  1. # $Id: FollowTail.pm,v 1.50 2004/04/20 00:15:54 sungo Exp $
  2.  
  3. package POE::Wheel::FollowTail;
  4.  
  5. use strict;
  6.  
  7. use vars qw($VERSION);
  8. $VERSION = do {my@r=(q$Revision: 1.50 $=~/\d+/g);sprintf"%d."."%04d"x$#r,@r};
  9.  
  10. use Carp;
  11. use Symbol;
  12. use POSIX qw(SEEK_SET SEEK_CUR SEEK_END);
  13. use POE qw(Wheel Driver::SysRW Filter::Line);
  14. use IO::Handle;
  15.  
  16. sub CRIMSON_SCOPE_HACK ($) { 0 }
  17.  
  18. sub SELF_HANDLE      () {  0 }
  19. sub SELF_FILENAME    () {  1 }
  20. sub SELF_DRIVER      () {  2 }
  21. sub SELF_FILTER      () {  3 }
  22. sub SELF_INTERVAL    () {  4 }
  23. sub SELF_EVENT_INPUT () {  5 }
  24. sub SELF_EVENT_ERROR () {  6 }
  25. sub SELF_EVENT_RESET () {  7 }
  26. sub SELF_UNIQUE_ID   () {  8 }
  27. sub SELF_STATE_READ  () {  9 }
  28. sub SELF_LAST_STAT   () { 10 }
  29. sub SELF_FOLLOW_MODE () { 11 }
  30.  
  31. sub MODE_TIMER  () { 0x01 } # Follow on a timer loop.
  32. sub MODE_SELECT () { 0x02 } # Follow via select().
  33.  
  34. # Turn on tracing.  A lot of debugging occurred just after 0.11.
  35. sub TRACE_RESET        () { 0 }
  36. sub TRACE_STAT         () { 0 }
  37. sub TRACE_STAT_VERBOSE () { 0 }
  38. sub TRACE_POLL         () { 0 }
  39.  
  40. # Tk doesn't provide a SEEK method, as of 800.022
  41. BEGIN {
  42.   if (exists $INC{'Tk.pm'}) {
  43.     eval <<'    EOE';
  44.       sub Tk::Event::IO::SEEK {
  45.         my $o = shift;
  46.         $o->wait(Tk::Event::IO::READABLE);
  47.         my $h = $o->handle;
  48.         sysseek($h, shift, shift);
  49.       }
  50.     EOE
  51.   }
  52. }
  53.  
  54. #------------------------------------------------------------------------------
  55.  
  56. sub new {
  57.   my $type = shift;
  58.   my %params = @_;
  59.  
  60.   croak "wheels no longer require a kernel reference as their first parameter"
  61.     if (@_ && (ref($_[0]) eq 'POE::Kernel'));
  62.  
  63.   croak "$type requires a working Kernel" unless (defined $poe_kernel);
  64.  
  65.   croak "FollowTail requires a Handle or Filename parameter, but not both"
  66.     unless $params{Handle} xor defined $params{Filename};
  67.  
  68.   my $driver = delete $params{Driver};
  69.   $driver = POE::Driver::SysRW->new() unless defined $driver;
  70.  
  71.   my $filter = delete $params{Filter};
  72.   $filter = POE::Filter::Line->new() unless defined $filter;
  73.  
  74.   croak "InputEvent required" unless defined $params{InputEvent};
  75.  
  76.   my $handle   = $params{Handle};
  77.   my $filename = $params{Filename};
  78.  
  79.   my @start_stat;
  80.   if (defined $filename) {
  81.     $handle = gensym();
  82.  
  83.     # FIFOs (named pipes) are opened R/W so they don't report EOF.
  84.     # TODO Make this nonfatal, in case the file doesn't exist but will
  85.     # later.  For example, the file may be caught in the middle of a
  86.     # rotation.
  87.     if (-p $filename) {
  88.       open $handle, "+<$filename" or
  89.         croak "can't open fifo $filename for R/W: $!";
  90.     }
  91.  
  92.     # Everything else is opened read-only.
  93.     else {
  94.       open $handle, "<$filename" or croak "can't open $filename: $!";
  95.     }
  96.     @start_stat = stat($filename);
  97.   }
  98.  
  99.   my $poll_interval = (
  100.     defined($params{PollInterval})
  101.     ?  $params{PollInterval}
  102.     : 1
  103.   );
  104.  
  105.   my $seek;
  106.   if (exists $params{SeekBack}) {
  107.     $seek = $params{SeekBack} * -1;
  108.     if (exists $params{Seek}) {
  109.       croak "can't have Seek and SeekBack at the same time";
  110.     }
  111.   }
  112.   elsif (exists $params{Seek}) {
  113.     $seek = $params{Seek};
  114.   }
  115.   else {
  116.     $seek = -4096;
  117.   }
  118.  
  119.   my $self = bless
  120.     [ $handle,                          # SELF_HANDLE
  121.       $filename,                        # SELF_FILENAME
  122.       $driver,                          # SELF_DRIVER
  123.       $filter,                          # SELF_FILTER
  124.       $poll_interval,                   # SELF_INTERVAL
  125.       delete $params{InputEvent},       # SELF_EVENT_INPUT
  126.       delete $params{ErrorEvent},       # SELF_EVENT_ERROR
  127.       delete $params{ResetEvent},       # SELF_EVENT_RESET
  128.       &POE::Wheel::allocate_wheel_id(), # SELF_UNIQUE_ID
  129.       undef,                            # SELF_STATE_READ
  130.       \@start_stat,                     # SELF_LAST_STAT
  131.       undef,                            # SELF_FOLLOW_MODE
  132.     ], $type;
  133.  
  134.   # SeekBack and partial-input discarding only work for plain files.
  135.   # SeekBack attempts to position the file pointer somewhere before
  136.   # the end of the file.  If it's specified, we assume the user knows
  137.   # where a record begins.  Otherwise we just seek back and discard
  138.   # everything to EOF so we can frame the input record.
  139.  
  140.   if (-f $handle) {
  141.     my $end = sysseek($handle, 0, SEEK_END);
  142.  
  143.     # Seeking back from EOF.
  144.     if ($seek < 0) {
  145.       if (defined($end) and ($end < -$seek)) {
  146.         sysseek($handle, 0, SEEK_SET);
  147.       }
  148.       else {
  149.         sysseek($handle, $seek, SEEK_END);
  150.       }
  151.     }
  152.  
  153.     # Seeking forward from the beginning of the file.
  154.     elsif ($seek > 0) {
  155.       if ($seek > $end) {
  156.         sysseek($handle, 0, SEEK_END);
  157.       }
  158.       else {
  159.         sysseek($handle, $seek, SEEK_SET);
  160.       }
  161.     }
  162.  
  163.     # If they set Seek to 0, we start at the beginning of the file.
  164.     # If it was SeekBack, we start at the end.
  165.     elsif (exists $params{Seek}) {
  166.       sysseek($handle, 0, SEEK_SET);
  167.     }
  168.     elsif (exists $params{SeekBack}) {
  169.       sysseek($handle, 0, SEEK_END);
  170.     }
  171.     else {
  172.       die;
  173.     }
  174.  
  175.     # Discard partial input chunks unless a SeekBack was specified.
  176.     unless (defined $params{SeekBack} or defined $params{Seek}) {
  177.       while (defined(my $raw_input = $driver->get($handle))) {
  178.         # Skip out if there's no more input.
  179.         last unless @$raw_input;
  180.         $filter->get($raw_input);
  181.       }
  182.     }
  183.  
  184.     # Start the timer loop.
  185.     $self->[SELF_FOLLOW_MODE] = MODE_TIMER;
  186.     $self->_define_timer_states();
  187.   }
  188.  
  189.   # Strange things that ought not be tailed?  Directories...
  190.   elsif (-d $handle) {
  191.     croak "FollowTail does not accept directories";
  192.   }
  193.  
  194.   # Otherwise it's not a plain file.  We won't honor SeekBack, and we
  195.   # will use select_read to watch the handle.
  196.   else {
  197.     carp "FollowTail does not support SeekBack on a special file"
  198.       if defined $params{SeekBack};
  199.     carp "FollowTail does not need PollInterval for special files"
  200.       if defined $params{PollInterval};
  201.  
  202.     # Start the select loop.
  203.     $self->[SELF_FOLLOW_MODE] = MODE_SELECT;
  204.     $self->_define_select_states();
  205.   }
  206.  
  207.   return $self;
  208. }
  209.  
  210. ### Define the select based polling loop.  This relies on stupid
  211. ### closure tricks to keep references to $self out of anonymous
  212. ### coderefs.  Otherwise a circular reference would occur, and the
  213. ### wheel would never self-destruct.
  214.  
  215. sub _define_select_states {
  216.   my $self = shift;
  217.  
  218.   my $filter      = $self->[SELF_FILTER];
  219.   my $driver      = $self->[SELF_DRIVER];
  220.   my $handle      = $self->[SELF_HANDLE];
  221.   my $unique_id   = $self->[SELF_UNIQUE_ID];
  222.   my $event_input = \$self->[SELF_EVENT_INPUT];
  223.   my $event_error = \$self->[SELF_EVENT_ERROR];
  224.   my $event_reset = \$self->[SELF_EVENT_RESET];
  225.  
  226.   TRACE_POLL and warn "defining select state";
  227.  
  228.   $poe_kernel->state
  229.     ( $self->[SELF_STATE_READ] = ref($self) . "($unique_id) -> select read",
  230.       sub {
  231.  
  232.         # Protects against coredump on older perls.
  233.         0 && CRIMSON_SCOPE_HACK('<');
  234.  
  235.         # The actual code starts here.
  236.         my ($k, $ses) = @_[KERNEL, SESSION];
  237.  
  238.         eval {
  239.           sysseek($handle, 0, SEEK_CUR);
  240.         };
  241.         $! = 0;
  242.  
  243.         TRACE_POLL and warn time . " read ok";
  244.  
  245.         if (defined(my $raw_input = $driver->get($handle))) {
  246.           if (@$raw_input) {
  247.             TRACE_POLL and warn time . " raw input";
  248.             foreach my $cooked_input (@{$filter->get($raw_input)}) {
  249.               TRACE_POLL and warn time . " cooked input";
  250.               $k->call($ses, $$event_input, $cooked_input, $unique_id);
  251.             }
  252.           }
  253.         }
  254.  
  255.         # Error reading.  Report the error if it's not EOF, or if it's
  256.         # EOF on a socket or TTY.  Shut down the select, too.
  257.         else {
  258.           if ($! or (-S $handle) or (-t $handle)) {
  259.             TRACE_POLL and warn time . " error: $!";
  260.             $$event_error and
  261.               $k->call($ses, $$event_error, 'read', ($!+0), $!, $unique_id);
  262.             $k->select($handle);
  263.           }
  264.           eval { IO::Handle::clearerr($handle) }; # could be a globref
  265.         }
  266.       }
  267.     );
  268.  
  269.   $poe_kernel->select_read($handle, $self->[SELF_STATE_READ]);
  270. }
  271.  
  272. ### Define the timer based polling loop.  This also relies on stupid
  273. ### closure tricks.
  274.  
  275. sub _define_timer_states {
  276.   my $self = shift;
  277.  
  278.   my $filter        = $self->[SELF_FILTER];
  279.   my $driver        = $self->[SELF_DRIVER];
  280.   my $unique_id     = $self->[SELF_UNIQUE_ID];
  281.   my $poll_interval = $self->[SELF_INTERVAL];
  282.   my $filename      = $self->[SELF_FILENAME];
  283.   my $last_stat     = $self->[SELF_LAST_STAT];
  284.   my $handle        = $self->[SELF_HANDLE];
  285.   my $state_read    = $self->[SELF_STATE_READ] =
  286.     ref($self) . "($unique_id) -> timer read";
  287.  
  288.   my $event_input   = \$self->[SELF_EVENT_INPUT];
  289.   my $event_error   = \$self->[SELF_EVENT_ERROR];
  290.   my $event_reset   = \$self->[SELF_EVENT_RESET];
  291.  
  292.   TRACE_POLL and warn "defining timer state";
  293.  
  294.   $poe_kernel->state
  295.     ( $state_read,
  296.       sub {
  297.  
  298.         # Protects against coredump on older perls.
  299.         0 && CRIMSON_SCOPE_HACK('<');
  300.  
  301.         # The actual code starts here.
  302.         my ($k, $ses) = @_[KERNEL, SESSION];
  303.  
  304.         eval {
  305.           if (defined $filename) {
  306.             my @new_stat = stat($filename);
  307.  
  308.             TRACE_STAT_VERBOSE and do {
  309.               my @test_new = @new_stat;   splice(@test_new, 8, 1, "(removed)");
  310.               my @test_old = @$last_stat; splice(@test_old, 8, 1, "(removed)");
  311.               warn "=== @test_new" if "@test_new" ne "@test_old";
  312.             };
  313.  
  314.             if (@new_stat) {
  315.  
  316.               # File shrank.  Consider it a reset.  Seek to the top of
  317.               # the file.
  318.               if ($new_stat[7] < $last_stat->[7]) {
  319.                 $$event_reset and $k->call($ses, $$event_reset, $unique_id);
  320.                 sysseek($handle, 0, SEEK_SET);
  321.               }
  322.  
  323.               $last_stat->[7] = $new_stat[7];
  324.  
  325.               # Something fundamental about the file changed.  Reopen it.
  326.               if ( $new_stat[1] != $last_stat->[1] or # inode's number
  327.                    $new_stat[0] != $last_stat->[0] or # inode's device
  328.                    $new_stat[6] != $last_stat->[6] or # device type
  329.                    $new_stat[3] != $last_stat->[3]    # number of links
  330.                  ) {
  331.  
  332.                 TRACE_STAT and do {
  333.                   warn "inode $new_stat[1] != old $last_stat->[1]\n"
  334.                     if $new_stat[1] != $last_stat->[1];
  335.                   warn "inode device $new_stat[0] != old $last_stat->[0]\n"
  336.                     if $new_stat[0] != $last_stat->[0];
  337.                   warn "device type $new_stat[6] != old $last_stat->[6]\n"
  338.                     if $new_stat[6] != $last_stat->[6];
  339.                   warn "number of links $new_stat[3] != old $last_stat->[3]\n"
  340.                     if $new_stat[3] != $last_stat->[3];
  341.                   warn "file size $new_stat[7] < old $last_stat->[7]\n"
  342.                     if $new_stat[7] < $last_stat->[7];
  343.                 };
  344.  
  345.                 @$last_stat = @new_stat;
  346.  
  347.                 close $handle;
  348.                 unless (open $handle, "<$filename") {
  349.                   $$event_error and
  350.                     $k->call( $ses, $$event_error, 'reopen',
  351.                               ($!+0), $!, $unique_id
  352.                             );
  353.                 }
  354.               }
  355.             }
  356.           }
  357.         };
  358.         $! = 0;
  359.  
  360.         TRACE_POLL and warn time . " read ok\n";
  361.  
  362.         # Got input.  Read a bunch of it, then poll again right away.
  363.         if (defined(my $raw_input = $driver->get($handle))) {
  364.           if (@$raw_input) {
  365.             TRACE_POLL and warn time . " raw input\n";
  366.             foreach my $cooked_input (@{$filter->get($raw_input)}) {
  367.               TRACE_POLL and warn time . " cooked input\n";
  368.               $k->call($ses, $$event_input, $cooked_input, $unique_id);
  369.             }
  370.           }
  371.           $k->yield($state_read);
  372.         }
  373.  
  374.         # Got an error of some sort.
  375.         else {
  376.           TRACE_POLL and warn time . " set delay\n";
  377.           if ($!) {
  378.             TRACE_POLL and warn time . " error: $!\n";
  379.             $$event_error and
  380.               $k->call($ses, $$event_error, 'read', ($!+0), $!, $unique_id);
  381.             $k->select($handle);
  382.           }
  383.           $k->delay($state_read, $poll_interval);
  384.           IO::Handle::clearerr($handle);
  385.         }
  386.       }
  387.     );
  388.  
  389.   $poe_kernel->yield($state_read);
  390. }
  391.  
  392. # ### Define the select states, and begin reading the special handle.
  393. # ### This also relies on stupid closure tricks.
  394.  
  395. #     $poe_kernel->select($handle, $self->[SELF_STATE_READ]);
  396.  
  397. #------------------------------------------------------------------------------
  398.  
  399. sub event {
  400.   my $self = shift;
  401.   push(@_, undef) if (scalar(@_) & 1);
  402.  
  403.   while (@_) {
  404.     my ($name, $event) = splice(@_, 0, 2);
  405.  
  406.     if ($name eq 'InputEvent') {
  407.       if (defined $event) {
  408.         $self->[SELF_EVENT_INPUT] = $event;
  409.       }
  410.       else {
  411.         carp "InputEvent requires an event name.  ignoring undef";
  412.       }
  413.     }
  414.     elsif ($name eq 'ErrorEvent') {
  415.       $self->[SELF_EVENT_ERROR] = $event;
  416.     }
  417.     elsif ($name eq 'ResetEvent') {
  418.       $self->[SELF_EVENT_RESET] = $event;
  419.     }
  420.     else {
  421.       carp "ignoring unknown FollowTail parameter '$name'";
  422.     }
  423.   }
  424.  
  425.   if ($self->[SELF_FOLLOW_MODE] & MODE_TIMER) {
  426.     $self->_define_timer_states();
  427.   }
  428.   elsif ($self->[SELF_FOLLOW_MODE] & MODE_SELECT) {
  429.     $self->_define_select_states();
  430.   }
  431.   else {
  432.     die;
  433.   }
  434. }
  435.  
  436. #------------------------------------------------------------------------------
  437.  
  438. sub DESTROY {
  439.   my $self = shift;
  440.  
  441.   # Remove our tentacles from our owner.
  442.   $poe_kernel->select($self->[SELF_HANDLE]);
  443.   $poe_kernel->delay($self->[SELF_STATE_READ]);
  444.  
  445.   if ($self->[SELF_STATE_READ]) {
  446.     $poe_kernel->state($self->[SELF_STATE_READ]);
  447.     undef $self->[SELF_STATE_READ];
  448.   }
  449.  
  450.   &POE::Wheel::free_wheel_id($self->[SELF_UNIQUE_ID]);
  451. }
  452.  
  453. #------------------------------------------------------------------------------
  454.  
  455. sub ID {
  456.   return $_[0]->[SELF_UNIQUE_ID];
  457. }
  458.  
  459. ###############################################################################
  460. 1;
  461.  
  462. __END__
  463.  
  464. =head1 NAME
  465.  
  466. POE::Wheel::FollowTail - follow the tail of an ever-growing file
  467.  
  468. =head1 SYNOPSIS
  469.  
  470.   $wheel = POE::Wheel::FollowTail->new(
  471.     Filename     => $file_name,                    # File to tail
  472.     Driver       => POE::Driver::Something->new(), # How to read it
  473.     Filter       => POE::Filter::Something->new(), # How to parse it
  474.     PollInterval => 1,                  # How often to check it
  475.     InputEvent   => $input_event_name,  # Event to emit upon input
  476.     ErrorEvent   => $error_event_name,  # Event to emit upon error
  477.     ResetEvent   => $reset_event_name,  # Event to emit on file reset
  478.     SeekBack     => $offset,            # How far from EOF to start
  479.     Seek         => $offset,            # How far from BOF to start
  480.   );
  481.  
  482.   $wheel = POE::Wheel::FollowTail->new(
  483.     Handle       => $open_file_handle,             # File to tail
  484.     Driver       => POE::Driver::Something->new(), # How to read it
  485.     Filter       => POE::Filter::Something->new(), # How to parse it
  486.     PollInterval => 1,                  # How often to check it
  487.     InputEvent   => $input_event_name,  # Event to emit upon input
  488.     ErrorEvent   => $error_event_name,  # Event to emit upon error
  489.     # No reset event available.
  490.     SeekBack     => $offset,            # How far from EOF to start
  491.     Seek         => $offset,            # How far from BOF to start
  492.   );
  493.  
  494. =head1 DESCRIPTION
  495.  
  496. FollowTail follows the end of an ever-growing file, such as a log of
  497. system events.  It generates events for each new record that is
  498. appended to its file.
  499.  
  500. This is a read-only wheel so it does not include a put() method.
  501.  
  502. =head1 PUBLIC METHODS
  503.  
  504. =over 2
  505.  
  506. =item event EVENT_TYPE => EVENT_NAME, ...
  507.  
  508. event() is covered in the POE::Wheel manpage.
  509.  
  510. FollowTail's event types are C<InputEvent>, C<ResetEvent>, and
  511. C<ErrorEvent>.
  512.  
  513. =item ID
  514.  
  515. The ID method returns a FollowTail wheel's unique ID.  This ID will be
  516. included in every event the wheel generates, and it can be used to
  517. match events with the wheels which generated them.
  518.  
  519. =back
  520.  
  521. =head1 EVENTS AND PARAMETERS
  522.  
  523. =over 2
  524.  
  525. =item Driver
  526.  
  527. Driver is a POE::Driver subclass that is used to read from and write
  528. to FollowTail's filehandle.  It encapsulates the low-level I/O
  529. operations needed to access a file so in theory FollowTail never needs
  530. to know about them.
  531.  
  532. POE::Wheel::FollowTail uses POE::Driver::SysRW if one is not
  533. specified.
  534.  
  535. =item Filter
  536.  
  537. Filter is a POE::Filter subclass that is used to parse input from the
  538. tailed file.  It encapsulates the lowest level of a protocol so that
  539. in theory FollowTail never needs to know about file formats.
  540.  
  541. POE::Wheel::FollowTail uses POE::Filter::Line if one is not
  542. specified.
  543.  
  544. =item PollInterval
  545.  
  546. PollInterval is the amount of time, in seconds, the wheel will wait
  547. before retrying after it has reached the end of the file.  This delay
  548. prevents the wheel from going into a CPU-sucking loop.
  549.  
  550. =item Seek
  551.  
  552. The Seek parameter tells FollowTail how far from the start of the file
  553. to start reading.  Its value is specified in bytes, and values greater
  554. than the file's current size will quietly cause FollowTail to start
  555. from the file's end.
  556.  
  557. A Seek parameter of 0 starts FollowTail at the beginning of the file.
  558. A negative Seek parameter emulates SeekBack: it seeks backwards from
  559. the end of the file.
  560.  
  561. Seek and SeekBack are mutually exclusive.  If Seek and SeekBack are
  562. not specified, FollowTail seeks 4096 bytes back from the end of the
  563. file and discards everything until the end of the file.  This helps
  564. ensure that FollowTail returns only complete records.
  565.  
  566. When either Seek or SeekBack is specified, FollowTail begins returning
  567. records from that position in the file.  It is possible that the first
  568. record returned may be incomplete.  In files with fixed-length
  569. records, it's possible to return entirely the wrong thing, all the
  570. time.  Please be careful.
  571.  
  572. =item SeekBack
  573.  
  574. The SeekBack parameter tells FollowTail how far back from the end of
  575. the file to start reading.  Its value is specified in bytes, and
  576. values greater than the file's current size will quietly cause
  577. FollowTail to ltart from the file's beginning.
  578.  
  579. A SeekBack parameter of 0 starts FollowTail at the end of the file.
  580. It's recommended to omit Seek and SeekBack to start from the end of a
  581. file.
  582.  
  583. A negative SeekBack parameter emulates Seek: it seeks forwards from
  584. the start of the file.
  585.  
  586. Seek and SeekBack are mutually exclusive.  If Seek and SeekBack are
  587. not specified, FollowTail seeks 4096 bytes back from the end of the
  588. file and discards everything until the end of the file.  This helps
  589. ensure that FollowTail returns only complete records.
  590.  
  591. When either Seek or SeekBack is specified, FollowTail begins returning
  592. records from that position in the file.  It is possible that the first
  593. record returned may be incomplete.  In files with fixed-length
  594. records, it's possible to return entirely the wrong thing, all the
  595. time.  Please be careful.
  596.  
  597. =item Handle
  598.  
  599. =item Filename
  600.  
  601. Either the Handle or Filename constructor parameter is required, but
  602. you cannot supply both.
  603.  
  604. FollowTail can watch a file or device that's already open.  Give it
  605. the open filehandle with its Handle parameter.
  606.  
  607. FollowTail can watch a file by name, given as the Filename parameter.
  608.  
  609. This wheel can detect files that have been "reset".  That is, it can
  610. tell when log files have been restarted due to a rotation or purge.
  611. For FollowTail to do this, though, it requires a Filename parameter.
  612. This is so FollowTail can reopen the file after it has reset.  See
  613. C<ResetEvent> elsewhere in this document.
  614.  
  615. =item InputEvent
  616.  
  617. InputEvent contains the name of an event which is emitted for every
  618. complete record read.  Every InputEvent event is accompanied by two
  619. parameters.  C<ARG0> contains the record which was read.  C<ARG1>
  620. contains the wheel's unique ID.
  621.  
  622. A sample InputEvent event handler:
  623.  
  624.   sub input_state {
  625.     my ($heap, $input, $wheel_id) = @_[HEAP, ARG0, ARG1];
  626.     print "Wheel $wheel_id received input: $input\n";
  627.   }
  628.  
  629. =item ResetEvent
  630.  
  631. ResetEvent contains the name of an event that's emitted every time a
  632. file is reset.
  633.  
  634. It's only available when watching files by name.  This is because
  635. FollowTail must reopen the file after it has been reset.
  636.  
  637. C<ARG0> contains the FollowTail wheel's unique ID.
  638.  
  639. =item ErrorEvent
  640.  
  641. ErrorEvent contains the event which is emitted whenever an error
  642. occurs.  Every ErrorEvent comes with four parameters:
  643.  
  644. C<ARG0> contains the name of the operation that failed.  This usually
  645. is 'read'.  Note: This is not necessarily a function name.  The wheel
  646. doesn't know which function its Driver is using.
  647.  
  648. C<ARG1> and C<ARG2> hold numeric and string values for C<$!>,
  649. respectively.  Note: FollowTail knows how to handle EAGAIN, so it will
  650. never return that error.
  651.  
  652. C<ARG3> contains the wheel's unique ID.
  653.  
  654. A sample ErrorEvent event handler:
  655.  
  656.   sub error_state {
  657.     my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
  658.     warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
  659.   }
  660.  
  661. =back
  662.  
  663. =head1 SEE ALSO
  664.  
  665. POE::Wheel.
  666.  
  667. The SEE ALSO section in L<POE> contains a table of contents covering
  668. the entire POE distribution.
  669.  
  670. =head1 BUGS
  671.  
  672. This wheel can't tail pipes and consoles on some systems.
  673.  
  674. Because this wheel is cooperatively multitasked, it may lose records
  675. just prior to a file reset.  For a more robust way to watch files,
  676. consider using POE::Wheel::Run and your operating system's native
  677. "tail" utility instead.
  678.  
  679.   $heap->{tail} = POE::Wheel::Run->new
  680.     ( Program     => [ "/usr/bin/tail", "-f", $file_name ],
  681.       StdoutEvent => "log_record",
  682.     );
  683.  
  684. =head1 AUTHORS & COPYRIGHTS
  685.  
  686. Please see L<POE> for more information about authors and contributors.
  687.  
  688. =cut
  689.