ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/Linux-Inotify2/Inotify2.pm
(Generate patch)

Comparing cvsroot/Linux-Inotify2/Inotify2.pm (file contents):
Revision 1.3 by root, Mon Aug 22 10:01:38 2005 UTC vs.
Revision 1.4 by root, Tue Aug 23 01:57:32 2005 UTC

… …
3Linux::Inotify2 - scalable directory/file change notification 3Linux::Inotify2 - scalable directory/file change notification
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Linux::Inotify2; 7 use Linux::Inotify2;
8
9 # create a new object
10 my $inotify = new Linux::Inotify2
11 or die "Unable to create new inotify object: $!";
12
13 # for Event:
14 Event->io (fd =>$inotify->fileno, poll => 'r', cb => sub { $inotify->poll });
15 # for Glib:
16 add_watch Glib::IO $inotify->fileno, in => sub { $inotify->poll };
17 # manually:
18 1 while $inotify->poll;
19
20 # add watchers
21 $inotify->watch ("/etc/passwd", IN_ACCESS, sub {
22 my $e = shift;
23 my $name = $e->fullname;
24 print "$name was accessed\n" if $e->IN_ACCESS;
25 print "$name is no longer mounted\n" if $e->IN_UNMOUNT;
26 print "$name is gone\n" if $e->IN_IGNORED;
27 print "events for $name have been lost\n" if $e->IN_Q_OVERFLOW;
28
29 # cancel this watcheR: remove no further events
30 $e->w->cancel;
31 });
8 32
9=head1 DESCRIPTION 33=head1 DESCRIPTION
10 34
11=head2 The Linux::Inotify2 Class 35=head2 The Linux::Inotify2 Class
12 36
… …
62 86
63 ENFILE The system limit on the total number of file descriptors has been reached. 87 ENFILE The system limit on the total number of file descriptors has been reached.
64 EMFILE The user limit on the total number of inotify instances has been reached. 88 EMFILE The user limit on the total number of inotify instances has been reached.
65 ENOMEM Insufficient kernel memory is available. 89 ENOMEM Insufficient kernel memory is available.
66 90
91Example:
92
93 my $inotify = new Linux::Inotify2
94 or die "Unable to create new inotify object: $!";
95
67=cut 96=cut
68 97
69sub new { 98sub new {
70 my ($class) = @_; 99 my ($class) = @_;
71 100
… …
74 return unless $fd >= 0; 103 return unless $fd >= 0;
75 104
76 bless { fd => $fd }, $class 105 bless { fd => $fd }, $class
77} 106}
78 107
79=item $watch = $inotify2->watch ($name, $mask, $cb) 108=item $watch = $inotify->watch ($name, $mask, $cb)
80 109
81Add a new watcher to the given notifier. The watcher will create events 110Add a new watcher to the given notifier. The watcher will create events
82on the pathname C<$name> as given in C<$mask>, which can be any of the 111on the pathname C<$name> as given in C<$mask>, which can be any of the
83following constants (all exported by default) ORed together: 112following constants (all exported by default) ORed together.
84 113
114"file" refers to any filesystem object in the watch'ed object (always a
115directory), that is files, directories, symlinks, device nodes etc., while
116"object" refers to the object the watch has been set on itself:
117
85 IN_ACCESS File was accessed 118 IN_ACCESS object was accessed
86 IN_MODIFY File was modified 119 IN_MODIFY object was modified
87 IN_ATTRIB Metadata changed 120 IN_ATTRIB object metadata changed
88 IN_CLOSE_WRITE Writable file was closed 121 IN_CLOSE_WRITE writable fd to file / to object was closed
89 IN_CLOSE_NOWRITE Unwritable file closed 122 IN_CLOSE_NOWRITE readonly fd to file / to object closed
90 IN_OPEN File was opened 123 IN_OPEN object was opened
91 IN_MOVED_FROM File was moved from X 124 IN_MOVED_FROM file was moved from this object (directory)
92 IN_MOVED_TO File was moved to Y 125 IN_MOVED_TO file was moved to this object (directory)
93 IN_CREATE Subfile was created 126 IN_CREATE file was created in this object (directory)
94 IN_DELETE Subfile was deleted 127 IN_DELETE file was deleted from this object (directory)
95 IN_DELETE_SELF Self was deleted 128 IN_DELETE_SELF object itself was deleted
129 IN_ALL_EVENTS all of the above events
130
96 IN_ONESHOT only send event once 131 IN_ONESHOT only send event once
97 IN_ALL_EVENTS All of the above events
98 132
99 IN_CLOSE Same as IN_CLOSE_WRITE | IN_CLOSE_NOWRITE 133 IN_CLOSE same as IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
100 IN_MOVE Same as IN_MOVED_FROM | IN_MOVED_TO 134 IN_MOVE same as IN_MOVED_FROM | IN_MOVED_TO
101 135
102C<$cb> is a perl code reference that is called for each event. It receives 136C<$cb> is a perl code reference that is called for each event. It receives
103a C<Linux::Inotify2::Event> object. 137a C<Linux::Inotify2::Event> object.
104 138
105The returned C<$watch> object is of class C<Linux::Inotify2::Watch>. 139The returned C<$watch> object is of class C<Linux::Inotify2::Watch>.
… …
145 Scalar::Util::weaken $w->{inotify}; 179 Scalar::Util::weaken $w->{inotify};
146 180
147 $w 181 $w
148} 182}
149 183
150=item $inotify2->fileno 184=item $inotify->fileno
151 185
152Returns the fileno for this notify object. You are responsible for calling 186Returns the fileno for this notify object. You are responsible for calling
153the C<poll> method when this fileno becomes ready for reading. 187the C<poll> method when this fileno becomes ready for reading.
154 188
155=cut 189=cut
156 190
157sub fileno { 191sub fileno {
158 $_[0]{fd} 192 $_[0]{fd}
159} 193}
160 194
161=item $count = $inotify2->poll 195=item $count = $inotify->poll
162 196
163Reads events from the kernel and handles them. If the notify fileno 197Reads events from the kernel and handles them. If the notify fileno is
164is blocking (the default), then this method waits for at least one 198blocking (the default), then this method waits for at least one event
165event. Otherwise it returns immediately when no pending events could be 199(and thus returns true unless an error occurs). Otherwise it returns
166read. 200immediately when no pending events could be read.
167 201
168Returns the count of events that have been handled. 202Returns the count of events that have been handled.
169 203
170=cut 204=cut
171
172# TODO: potential race with recently-canceled watchers
173 205
174sub poll { 206sub poll {
175 my ($self) = @_; 207 my ($self) = @_;
176 208
177 for (inotify_read $self->{fd}) { 209 my @ev = inotify_read $self->{fd};
210
211 for (@ev) {
178 $_->{w} = $self->{w}{$_->{wd}} 212 my $w = $_->{w} = $self->{w}{$_->{wd}}
179 or next; # no such watcher 213 or next; # no such watcher
214
215 exists $self->{ignore}{$_->{wd}}
216 and next; # watcher has been canceled
217
180 $_->{w}{cb}->(bless $_, Linux::Inotify2::Event); 218 $w->{cb}->(bless $_, Linux::Inotify2::Event);
219 $w->cancel if $_->{mask} & (IN_IGNORED | IN_UNMOUNT);
181 } 220 }
221
222 delete $self->{ignore};
223
224 scalar @ev
182} 225}
183 226
184sub DESTROY { 227sub DESTROY {
185 inotify_close $_[0]{fd} 228 inotify_close $_[0]{fd}
186} 229}
… …
216=item $event->{mask} 259=item $event->{mask}
217 260
218The received event mask. In addition the the events described for 261The received event mask. In addition the the events described for
219C<$inotify->watch>, the following flags (exported by default) can be set: 262C<$inotify->watch>, the following flags (exported by default) can be set:
220 263
221 IN_ISDIR event occurred against dir 264 IN_ISDIR event object is a directory
222 265
223 IN_UNMOUNT Backing fs was unmounted
224 IN_Q_OVERFLOW Event queued overflowed 266 IN_Q_OVERFLOW event queue overflowed
267
268 # when the following flags are set, then watchers are canceled automatically
269 IN_UNMOUNT filesystem for watch'ed object was unmounted
225 IN_IGNORED File was ignored (no more events will be delivered) 270 IN_IGNORED file was ignored/is gone (no more events are delivered)
226 271
227=item $event->IN_xxx 272=item $event->IN_xxx
228 273
229Returns a boolean that returns true if the event mask matches the 274Returns a boolean that returns true if the event mask matches the
230event. All of the C<IN_xxx> constants can be used as methods. 275event. All of the C<IN_xxx> constants can be used as methods.
… …
302} 347}
303 348
304sub cancel { 349sub cancel {
305 my ($self) = @_; 350 my ($self) = @_;
306 351
352 my $inotify = delete $self->{inotify}
353 or return 1; # already canceled
354
355 delete $inotify->{w}{$self->{wd}}; # we are no longer there
356 $inotify->{ignore}{$self->{wd}} = 1; # ignore further events for one poll
357
307 (Linux::Inotify2::inotify_rm_watch $self->{inotify}{fd}, $self->{wd}) 358 (Linux::Inotify2::inotify_rm_watch $inotify->{fd}, $self->{wd})
308 ? 1 : undef 359 ? 1 : undef
309} 360}
310 361
311=head1 SEE ALSO 362=head1 SEE ALSO
312 363

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines