1IO::Async::File(3)    User Contributed Perl Documentation   IO::Async::File(3)
2
3
4

NAME

6       "IO::Async::File" - watch a file for changes
7

SYNOPSIS

9          use IO::Async::File;
10
11          use IO::Async::Loop;
12          my $loop = IO::Async::Loop->new;
13
14          my $file = IO::Async::File->new(
15             filename => "config.ini",
16             on_mtime_changed => sub {
17                my ( $self ) = @_;
18                print STDERR "Config file has changed\n";
19                reload_config( $self->handle );
20             }
21          );
22
23          $loop->add( $file );
24
25          $loop->run;
26

DESCRIPTION

28       This subclass of IO::Async::Notifier watches an open filehandle or
29       named filesystem entity for changes in its stat() fields. It invokes
30       various events when the values of these fields change. It is most often
31       used to watch a file for size changes; for this task see also
32       IO::Async::FileStream.
33
34       While called "File", it is not required that the watched filehandle be
35       a regular file. It is possible to watch anything that stat(2) may be
36       called on, such as directories or other filesystem entities.
37

EVENTS

39       The following events are invoked, either using subclass methods or CODE
40       references in parameters.
41
42   on_dev_changed $new_dev, $old_dev
43   on_ino_changed $new_ino, $old_ino
44   ...
45   on_ctime_changed $new_ctime, $old_ctime
46       Invoked when each of the individual stat() fields have changed. All the
47       stat() fields are supported apart from "blocks" and "blksize". Each is
48       passed the new and old values of the field.
49
50   on_devino_changed $new_stat, $old_stat
51       Invoked when either of the "dev" or "ino" fields have changed. It is
52       passed two File::stat instances containing the complete old and new
53       stat() fields. This can be used to observe when a named file is
54       renamed; it will not be observed to happen on opened filehandles.
55
56   on_stat_changed $new_stat, $old_stat
57       Invoked when any of the stat() fields have changed. It is passed two
58       File::stat instances containing the old and new stat() fields.
59

PARAMETERS

61       The following named parameters may be passed to "new" or "configure".
62
63   handle => IO
64       The opened filehandle to watch for stat() changes if "filename" is not
65       supplied.
66
67   filename => STRING
68       Optional. If supplied, watches the named file rather than the
69       filehandle given in "handle". The file will be opened for reading and
70       then watched for renames. If the file is renamed, the new filename is
71       opened and tracked similarly after closing the previous file.
72
73   interval => NUM
74       Optional. The interval in seconds to poll the filehandle using stat(2)
75       looking for size changes. A default of 2 seconds will be applied if not
76       defined.
77

METHODS

79   handle
80          $handle = $file->handle
81
82       Returns the filehandle currently associated with the instance; either
83       the one passed to the "handle" parameter, or opened from the "filename"
84       parameter.
85

AUTHOR

87       Paul Evans <leonerd@leonerd.org.uk>
88
89
90
91perl v5.36.0                      2023-01-20                IO::Async::File(3)
Impressum