1IO::Async::FileStream(3U)ser Contributed Perl DocumentatiIoOn::Async::FileStream(3)
2
6 "IO::Async::FileStream" - read the tail of a file
7
9 use IO::Async::FileStream;
10 use IO::Async::Loop;
12 my $loop = IO::Async::Loop->new;
13 open my $logh, "<", "var/logs/daemon.log" or
15 die "Cannot open logfile - $!";
16 my $filestream = IO::Async::FileStream->new(
18 read_handle => $logh,
19 on_initial => sub {
21 my ( $self ) = @_;
22 $self->seek_to_last( "\n" );
23 },
24 on_read => sub {
26 my ( $self, $buffref ) = @_;
27 while( $$buffref =~ s/^(.*\n)// ) {
29 print "Received a line $1";
30 }
31 return 0;
33 },
34 );
35 $loop->add( $filestream );
37 $loop->run;
39
41 This subclass of IO::Async::Stream allows reading the end of a regular
42 file which is being appended to by some other process. It invokes the
43 "on_read" event when more data has been added to the file.
44 This class provides an API identical to IO::Async::Stream when given a
46 "read_handle"; it should be treated similarly. In particular, it can be
47 given an "on_read" handler, or subclassed to provide an "on_read"
48 method, or even used as the "transport" for an
49 IO::Async::Protocol::Stream object.
50 It will not support writing.
52 To watch a file, directory, or other filesystem entity for updates of
54 other properties, such as "mtime", see also IO::Async::File.
55
57 The following events are invoked, either using subclass methods or CODE
58 references in parameters.
59 Because this is a subclass of IO::Async::Stream in read-only mode, all
61 the events supported by "Stream" relating to the read handle are
62 supported here. This is not a full list; see also the documentation
63 relating to IO::Async::Stream.
64 $ret = on_read \$buffer, $eof
66 Invoked when more data is available in the internal receiving buffer.
67 Note that $eof only indicates that all the data currently available in
69 the file has now been read; in contrast to a regular IO::Async::Stream,
70 this object will not stop watching after this condition. Instead, it
71 will continue watching the file for updates.
72 on_truncated
74 Invoked when the file size shrinks. If this happens, it is presumed
75 that the file content has been replaced. Reading will then commence
76 from the start of the file.
77 on_initial $size
79 Invoked the first time the file is looked at. It is passed the initial
80 size of the file. The code implementing this method can use the "seek"
81 or "seek_to_last" methods to set the initial read position in the file
82 to skip over some initial content.
83 This method may be useful to skip initial content in the file, if the
85 object should only respond to new content added after it was created.
86
88 The following named parameters may be passed to "new" or "configure",
89 in addition to the parameters relating to reading supported by
90 IO::Async::Stream.
91 filename => STRING
93 Optional. If supplied, watches the named file rather than the
94 filehandle given in "read_handle". The file will be opened by the
95 constructor, and then watched for renames. If the file is renamed, the
96 new filename is opened and tracked similarly after closing the previous
97 file.
98 interval => NUM
100 Optional. The interval in seconds to poll the filehandle using stat(2)
101 looking for size changes. A default of 2 seconds will be applied if not
102 defined.
103
105 seek
106 $filestream->seek( $offset, $whence )
107 Callable only during the "on_initial" event. Moves the read position in
109 the filehandle to the given offset. $whence is interpreted as for
110 "sysseek", should be either "SEEK_SET", "SEEK_CUR" or "SEEK_END". Will
111 be set to "SEEK_SET" if not provided.
112 Normally this would be used to seek to the end of the file, for example
114 on_initial => sub {
116 my ( $self, $filesize ) = @_;
117 $self->seek( $filesize );
118 }
119 seek_to_last
121 $success = $filestream->seek_to_last( $str_pattern, %opts )
122 Callable only during the "on_initial" event. Attempts to move the read
124 position in the filehandle to just after the last occurrence of a given
125 match. $str_pattern may be a literal string or regexp pattern.
126 Returns a true value if the seek was successful, or false if not. Takes
128 the following named arguments:
129 blocksize => INT
131 Optional. Read the file in blocks of this size. Will take a
132 default of 8KiB if not defined.
133 horizon => INT
135 Optional. Give up looking for a match after this number of
136 bytes. Will take a default value of 4 times the blocksize if
137 not defined.
138 To force it to always search through the entire file contents,
140 set this explicitly to 0.
141 Because regular file reading happens synchronously, this entire method
143 operates entirely synchronously. If the file is very large, it may take
144 a while to read back through the entire contents. While this is
145 happening no other events can be invoked in the process.
146 When looking for a string or regexp match, this method appends the
148 previously-read buffer to each block read from the file, in case a
149 match becomes split across two reads. If "blocksize" is reduced to a
150 very small value, take care to ensure it isn't so small that a match
151 may not be noticed.
152 This is most likely useful for seeking after the last complete line in
154 a line-based log file, to commence reading from the end, while still
155 managing to capture any partial content that isn't yet a complete line.
156 on_initial => sub {
158 my $self = shift;
159 $self->seek_to_last( "\n" );
160 }
161
163 • Move the actual file update watching code into IO::Async::Loop,
164 possibly as a new watch/unwatch method pair "watch_file".
165 • Consider if a construction-time parameter of "seek_to_end" or
167 "seek_to_last" might be neater than a small code block in
168 "on_initial", if that turns out to be the only or most common form
169 of use.
170
172 Paul Evans <leonerd@leonerd.org.uk>
173perl v5.36.0 2023-01-20 IO::Async::FileStream(3)