1POE::Wheel::FollowTail(U3s)er Contributed Perl DocumentatPiOoEn::Wheel::FollowTail(3)
2
6 POE::Wheel::FollowTail - follow the tail of an ever-growing file
7
9 $wheel = POE::Wheel::FollowTail->new(
10 Filename => $file_name, # File to tail
11 Driver => POE::Driver::Something->new(), # How to read it
12 Filter => POE::Filter::Something->new(), # How to parse it
13 PollInterval => 1, # How often to check it
14 InputEvent => $input_event_name, # Event to emit upon input
15 ErrorEvent => $error_event_name, # Event to emit upon error
16 ResetEvent => $reset_event_name, # Event to emit on file reset
17 SeekBack => $offset, # How far from EOF to start
18 Seek => $offset, # How far from BOF to start
19 );
20 $wheel = POE::Wheel::FollowTail->new(
22 Handle => $open_file_handle, # File to tail
23 Driver => POE::Driver::Something->new(), # How to read it
24 Filter => POE::Filter::Something->new(), # How to parse it
25 PollInterval => 1, # How often to check it
26 InputEvent => $input_event_name, # Event to emit upon input
27 ErrorEvent => $error_event_name, # Event to emit upon error
28 # No reset event available.
29 SeekBack => $offset, # How far from EOF to start
30 Seek => $offset, # How far from BOF to start
31 );
32 $pos = $wheel->tell(); # Get the current log position.
34
36 FollowTail follows the end of an ever-growing file, such as a log of
37 system events. It generates events for each new record that is
38 appended to its file.
39 This is a read-only wheel so it does not include a put() method.
41
43 new new() creates a new wheel, returning the wheels reference.
44
46 event EVENT_TYPE => EVENT_NAME, ...
47 event() is covered in the POE::Wheel manpage.
48 FollowTail's event types are "InputEvent", "ResetEvent", and
50 "ErrorEvent".
51 ID
53 The ID method returns a FollowTail wheel's unique ID. This ID will
54 be included in every event the wheel generates, and it can be used to
55 match events with the wheels which generated them.
56 tell
58 Returns where POE::Wheel::FollowTail is currently in the log file.
59 tell() may be useful for seeking back into a file when resuming tail‐
60 ing.
61 my $pos = $wheel->tell();
63 FollowTail generally reads ahead of the data it returns, so the file
65 position is not necessarily the point after the last record you have
66 received.
67
69 Driver
70 Driver is a POE::Driver subclass that is used to read from and write
71 to FollowTail's filehandle. It encapsulates the low-level I/O opera‐
72 tions needed to access a file so in theory FollowTail never needs to
73 know about them.
74 POE::Wheel::FollowTail uses POE::Driver::SysRW if one is not speci‐
76 fied.
77 Filter
79 Filter is a POE::Filter subclass that is used to parse input from the
80 tailed file. It encapsulates the lowest level of a protocol so that
81 in theory FollowTail never needs to know about file formats.
82 POE::Wheel::FollowTail uses POE::Filter::Line if one is not speci‐
84 fied.
85 PollInterval
87 PollInterval is the amount of time, in seconds, the wheel will wait
88 before retrying after it has reached the end of the file. This delay
89 prevents the wheel from going into a CPU-sucking loop.
90 Seek
92 The Seek parameter tells FollowTail how far from the start of the
93 file to start reading. Its value is specified in bytes, and values
94 greater than the file's current size will quietly cause FollowTail to
95 start from the file's end.
96 A Seek parameter of 0 starts FollowTail at the beginning of the file.
98 A negative Seek parameter emulates SeekBack: it seeks backwards from
99 the end of the file.
100 Seek and SeekBack are mutually exclusive. If Seek and SeekBack are
102 not specified, FollowTail seeks 4096 bytes back from the end of the
103 file and discards everything until the end of the file. This helps
104 ensure that FollowTail returns only complete records.
105 When either Seek or SeekBack is specified, FollowTail begins return‐
107 ing records from that position in the file. It is possible that the
108 first record returned may be incomplete. In files with fixed-length
109 records, it's possible to return entirely the wrong thing, all the
110 time. Please be careful.
111 SeekBack
113 The SeekBack parameter tells FollowTail how far back from the end of
114 the file to start reading. Its value is specified in bytes, and val‐
115 ues greater than the file's current size will quietly cause Follow‐
116 Tail to start from the file's beginning.
117 A SeekBack parameter of 0 starts FollowTail at the end of the file.
119 It's recommended to omit Seek and SeekBack to start from the end of a
120 file.
121 A negative SeekBack parameter emulates Seek: it seeks forwards from
123 the start of the file.
124 Seek and SeekBack are mutually exclusive. If Seek and SeekBack are
126 not specified, FollowTail seeks 4096 bytes back from the end of the
127 file and discards everything until the end of the file. This helps
128 ensure that FollowTail returns only complete records.
129 When either Seek or SeekBack is specified, FollowTail begins return‐
131 ing records from that position in the file. It is possible that the
132 first record returned may be incomplete. In files with fixed-length
133 records, it's possible to return entirely the wrong thing, all the
134 time. Please be careful.
135 Handle
137 Filename
138 Either the Handle or Filename constructor parameter is required, but
139 you cannot supply both.
140 FollowTail can watch a file or device that's already open. Give it
142 the open filehandle with its Handle parameter.
143 FollowTail can watch a file by name, given as the Filename parameter.
145 The named file does not need to exist. FollowTail will wait for it
146 to appear.
147 This wheel can detect files that have been "reset". That is, it can
149 tell when log files have been restarted due to a rotation or purge.
150 For FollowTail to do this, though, it requires a Filename parameter.
151 This is so FollowTail can reopen the file after it has reset. See
152 "ResetEvent" elsewhere in this document.
153 InputEvent
155 InputEvent contains the name of an event which is emitted for every
156 complete record read. Every InputEvent event is accompanied by two
157 parameters. "ARG0" contains the record which was read. "ARG1" con‐
158 tains the wheel's unique ID.
159 A sample InputEvent event handler:
161 sub input_state {
163 my ($heap, $input, $wheel_id) = @_[HEAP, ARG0, ARG1];
164 print "Wheel $wheel_id received input: $input\n";
165 }
166 ResetEvent
168 ResetEvent contains the name of an event that's emitted every time a
169 file is reset.
170 It's only available when watching files by name. This is because
172 FollowTail must reopen the file after it has been reset.
173 "ARG0" contains the FollowTail wheel's unique ID.
175 ErrorEvent
177 ErrorEvent contains the event which is emitted whenever an error
178 occurs. Every ErrorEvent comes with four parameters:
179 "ARG0" contains the name of the operation that failed. This usually
181 is 'read'. Note: This is not necessarily a function name. The wheel
182 doesn't know which function its Driver is using.
183 "ARG1" and "ARG2" hold numeric and string values for $!, respec‐
185 tively. Note: FollowTail knows how to handle EAGAIN, so it will
186 never return that error.
187 "ARG3" contains the wheel's unique ID.
189 A sample ErrorEvent event handler:
191 sub error_state {
193 my ($operation, $errnum, $errstr, $wheel_id) = @_[ARG0..ARG3];
194 warn "Wheel $wheel_id generated $operation error $errnum: $errstr\n";
195 }
196
198 POE::Wheel.
199 The SEE ALSO section in POE contains a table of contents covering the
201 entire POE distribution.
202
204 This wheel can't tail pipes and consoles on some systems.
205
207 Please see POE for more information about authors and contributors.
208perl v5.8.8 2006-09-01 POE::Wheel::FollowTail(3)