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

Comparing cvsroot/Linux-Inotify2/README (file contents):
Revision 1.1 by root, Mon Aug 22 09:51:38 2005 UTC vs.
Revision 1.2 by root, Mon Aug 22 10:00:10 2005 UTC

1NAME 1NAME
2 Linux::AIO - linux-specific aio implemented using clone 2 Linux::Inotify2 - scalable directory/file change notification
3 3
4SYNOPSIS 4SYNOPSIS
5 use Linux::AIO; 5 use Linux::Inotify2;
6
7 # This module has been mostly superseded by IO::AIO.
8 6
9DESCRIPTION 7DESCRIPTION
10 *This module has been mostly superseded by IO::AIO, which is API 8 The Linux::Inotify2 Class
11 compatible.* 9 This module implements an interface to the linux inotify file/directory
10 change notification sytem.
12 11
13 This module implements asynchronous I/O using the means available to 12 It has a number of advantages over the Linux::Inotfy module:
14 Linux - clone. It does not hook into the POSIX aio_* functions because
15 Linux does not yet support these in the kernel (even as of 2.6.12, only
16 O_DIRECT files are supported) and even if, it would only allow aio_read
17 and write, not open, stat and so on.
18 13
19 Instead, in this module a number of (non-posix) threads are started that 14 - it is portable (Linux::Inotify only works on x86)
20 execute your read/writes and signal their completion. You don't need 15 - the equivalent of fullname works correctly
21 thread support in your libc or perl, and the threads created by this 16 - it is better documented
22 module will not be visible to the pthreads library. 17 - it has callback-style interface, which is better suited for
18 integration.
23 19
24 NOTICE: the threads created by this module will automatically be killed 20 my $inotify = new Linux::Inotify2
25 when the thread calling min_parallel exits. Make sure you only ever call 21 Create a new notify object and return it. A notify object is kind of
26 min_parallel from the same thread that loaded this module. 22 a container that stores watches on filesystem names and is
23 responsible for handling event data.
27 24
28 Although the module will work with in the presence of other threads, it 25 On error, "undef" is returned and $! will be set accordingly. The
29 is not reentrant, so use appropriate locking yourself. 26 followign errors are documented:
30 27
31 API NOTES 28 ENFILE The system limit on the total number of file descriptors has been reached.
32 All the "aio_*" calls are more or less thin wrappers around the syscall 29 EMFILE The user limit on the total number of inotify instances has been reached.
33 with the same name (sans "aio_"). The arguments are similar or 30 ENOMEM Insufficient kernel memory is available.
34 identical, and they all accept an additional $callback argument which
35 must be a code reference. This code reference will get called with the
36 syscall return code (e.g. most syscalls return -1 on error, unlike perl,
37 which usually delivers "false") as it's sole argument when the given
38 syscall has been executed asynchronously.
39 31
40 All functions that expect a filehandle will also accept a file 32 $watch = $inotify2->watch ($name, $mask, $cb)
41 descriptor. 33 Add a new watcher to the given notifier. The watcher will create
34 events on the pathname $name as given in $mask, which can be any of
35 the following constants (all exported by default) ORed together:
42 36
43 The filenames you pass to these routines *must* be absolute. The reason 37 IN_ACCESS File was accessed
44 is that at the time the request is being executed, the current working 38 IN_MODIFY File was modified
45 directory could have changed. Alternatively, you can make sure that you 39 IN_ATTRIB Metadata changed
46 never change the current working directory. 40 IN_CLOSE_WRITE Writtable file was closed
41 IN_CLOSE_NOWRITE Unwrittable file closed
42 IN_OPEN File was opened
43 IN_MOVED_FROM File was moved from X
44 IN_MOVED_TO File was moved to Y
45 IN_CREATE Subfile was created
46 IN_DELETE Subfile was deleted
47 IN_DELETE_SELF Self was deleted
48 IN_ONESHOT only send event once
49 IN_ALL_EVENTS All of the above events
47 50
48 Linux::AIO::min_parallel $nthreads 51 IN_CLOSE Same as IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
49 Set the minimum number of AIO threads to $nthreads. The default is 52 IN_MOVE Same as IN_MOVED_FROM | IN_MOVED_TO
50 1, which means a single asynchronous operation can be done at one
51 time (the number of outstanding operations, however, is unlimited).
52 53
53 It is recommended to keep the number of threads low, as some linux 54 $cb is a perl code reference that is called for each event. It
54 kernel versions will scale negatively with the number of threads 55 receives a "Linux::Inotify2::Event" object.
55 (higher parallelity => MUCH higher latency).
56 56
57 Under normal circumstances you don't need to call this function, as 57 The returned $watch object is of class "Linux::Inotify2::Watch".
58 this module automatically starts a single async thread.
59 58
60 Linux::AIO::max_parallel $nthreads 59 On error, "undef" is returned and $! will be set accordingly. The
61 Sets the maximum number of AIO threads to $nthreads. If more than 60 following errors are documented:
62 the specified number of threads are currently running, kill them.
63 This function blocks until the limit is reached.
64 61
65 This module automatically runs "max_parallel 0" at program end, to 62 EBADF The given file descriptor is not valid.
66 ensure that all threads are killed and that there are no outstanding 63 EINVAL The given event mask contains no legal events.
67 requests. 64 ENOMEM Insufficient kernel memory was available.
65 ENOSPC The user limit on the total number of inotify watches was reached or the kernel failed to allocate a needed resource.
66 EACCESS Read access to the given file is not permitted.
68 67
69 Under normal circumstances you don't need to call this function. 68 Example, show when "/etc/passwd" gets accessed and/or modified once:
70 69
71 $fileno = Linux::AIO::poll_fileno 70 $inotify->watch ("/etc/passwd", IN_ACCESS | IN_MODIFY, sub {
72 Return the *request result pipe filehandle*. This filehandle must be 71 my $e = shift;
73 polled for reading by some mechanism outside this module (e.g. Event 72 print "$e->{w}{name} was accessed\n" if $e->IN_ACCESS;
74 or select, see below). If the pipe becomes readable you have to call 73 print "$e->{w}{name} was modified\n" if $e->IN_MODIFY;
75 "poll_cb" to check the results. 74 print "$e->{w}{name} is no longer mounted\n" if $e->IN_UNMOUNT;
75 print "events for $e->{w}{name} have been lost\n" if $e->IN_Q_OVERFLOW;
76 76
77 See "poll_cb" for an example. 77 $e->w->cancel;
78 });
78 79
79 Linux::AIO::poll_cb 80 $inotify2->fileno
80 Process all outstanding events on the result pipe. You have to call 81 Returns the fileno for this notify object. You are responsible for
81 this regularly. Returns the number of events processed. Returns 82 calling the "poll" method when this fileno becomes ready for
82 immediately when no events are outstanding. 83 reading.
83 84
84 You can use Event to multiplex, e.g.: 85 $count = $inotify2->poll
86 Reads events from the kernel and handles them. If the notify fileno
87 is blocking (the default), then this method waits for at least one
88 event. Otherwise it returns immediately when no pending events could
89 be read.
85 90
86 Event->io (fd => Linux::AIO::poll_fileno, 91 Returns the count of events that have been handled.
87 poll => 'r', async => 1,
88 cb => \&Linux::AIO::poll_cb);
89 92
90 Linux::AIO::poll_wait 93 The Linux::Inotify2::Event Class
91 Wait till the result filehandle becomes ready for reading (simply 94 Objects of this class are handed as first argument to the watch
92 does a select on the filehandle. This is useful if you want to 95 callback. It has the following members and methods:
93 synchronously wait for some requests to finish).
94 96
95 See "nreqs" for an example. 97 $event->w
98 $event->{w}
99 The watcher object for this event.
96 100
97 Linux::AIO::nreqs 101 $event->name
98 Returns the number of requests currently outstanding. 102 $event->{name}
103 The path of the filesystem object, relative to the watch name.
99 104
100 Example: wait till there are no outstanding requests anymore: 105 $watch->fullname
106 Returns the "full" name of the relevant object, i.e. including the
107 "name" component of the watcher.
101 108
102 Linux::AIO::poll_wait, Linux::AIO::poll_cb 109 $event->mask
103 while Linux::AIO::nreqs; 110 $event->{mask}
111 The received event mask. In addition the the events described for
112 "$inotify-"watch>, the following flags (exported by default) can be
113 set:
104 114
105 aio_open $pathname, $flags, $mode, $callback 115 IN_ISDIR event occurred against dir
106 Asynchronously open or create a file and call the callback with the
107 filedescriptor (NOT a perl filehandle, sorry for that, but watch
108 out, this might change in the future).
109 116
110 The pathname passed to "aio_open" must be absolute. See API NOTES, 117 IN_UNMOUNT Backing fs was unmounted
111 above, for an explanation. 118 IN_Q_OVERFLOW Event queued overflowed
119 IN_IGNORED File was ignored (no more events will be delivered)
112 120
113 The $mode argument is a bitmask. See the "Fcntl" module for a list. 121 $event->IN_xxx
114 They are the same as used in "sysopen". 122 Returns a boolean that returns true if the event mask matches the
123 event. All of the "IN_xxx" constants can be used as methods.
115 124
116 Example: 125 $event->cookie
126 $event->{cookie}
127 The event cookie, can be used to synchronize two related events.
117 128
118 aio_open "/etc/passwd", O_RDONLY, 0, sub { 129 The Linux::Inotify2::Watch Class
119 if ($_[0] >= 0) { 130 Watch objects are created by calling the "watch" method of a notifier.
120 open my $fh, "<&=$_[0]";
121 print "open successful, fh is $fh\n";
122 ...
123 } else {
124 die "open failed: $!\n";
125 }
126 };
127 131
128 aio_close $fh, $callback 132 It has the following members and methods:
129 Asynchronously close a file and call the callback with the result
130 code.
131 133
132 aio_read $fh,$offset,$length, $data,$dataoffset,$callback 134 $watch->name
133 aio_write $fh,$offset,$length, $data,$dataoffset,$callback 135 $watch->{name}
134 Reads or writes "length" bytes from the specified "fh" and "offset" 136 The name as specified in the "watch" call. For the object itself, this
135 into the scalar given by "data" and offset "dataoffset" and calls 137 is the empty string. For directory watches, this is the name of the
136 the callback without the actual number of bytes read (or -1 on 138 entry without leading path elements.
137 error, just like the syscall).
138 139
139 Example: Read 15 bytes at offset 7 into scalar $buffer, strating at 140 $watch->mask
140 offset 0 within the scalar: 141 $watch->{mask}
142 The mask as specified in the "watch" call.
141 143
142 aio_read $fh, 7, 15, $buffer, 0, sub { 144 $watch->cb ([new callback])
143 $_[0] >= 0 or die "read error: $!"; 145 $watch->{cb}
144 print "read <$buffer>\n"; 146 The callback as specified in the "watch" call. Can optionally be
145 }; 147 changed.
146 148
147 aio_readahead $fh,$offset,$length, $callback 149 $watch->cancel
148 Asynchronously reads the specified byte range into the page cache, 150 Cancels/removes this watch. Future events, even if already queued
149 using the "readahead" syscall. 151 queued, will not be handled and resources will be freed.
150
151 readahead() populates the page cache with data from a file so that
152 subsequent reads from that file will not block on disk I/O. The
153 $offset argument specifies the starting point from which data is to
154 be read and $length specifies the number of bytes to be read. I/O is
155 performed in whole pages, so that offset is effectively rounded down
156 to a page boundary and bytes are read up to the next page boundary
157 greater than or equal to (off-set+length). aio_readahead() does not
158 read beyond the end of the file. The current file offset of the file
159 is left unchanged.
160
161 aio_stat $fh_or_path, $callback
162 aio_lstat $fh, $callback
163 Works like perl's "stat" or "lstat" in void context. The callback
164 will be called after the stat and the results will be available
165 using "stat _" or "-s _" etc...
166
167 The pathname passed to "aio_stat" must be absolute. See API NOTES,
168 above, for an explanation.
169
170 Currently, the stats are always 64-bit-stats, i.e. instead of
171 returning an error when stat'ing a large file, the results will be
172 silently truncated unless perl itself is compiled with large file
173 support.
174
175 Example: Print the length of /etc/passwd:
176
177 aio_stat "/etc/passwd", sub {
178 $_[0] and die "stat failed: $!";
179 print "size is ", -s _, "\n";
180 };
181
182 aio_unlink $pathname, $callback
183 Asynchronously unlink (delete) a file and call the callback with the
184 result code.
185
186 aio_fsync $fh, $callback
187 Asynchronously call fsync on the given filehandle and call the
188 callback with the fsync result code.
189
190 aio_fdatasync $fh, $callback
191 Asynchronously call fdatasync on the given filehandle and call the
192 callback with the fdatasync result code.
193
194BUGS
195 This module has been extensively tested in a large and very busy
196 webserver for many years now.
197
198 - aio_open gives a fd, but all other functions expect a perl filehandle.
199 152
200SEE ALSO 153SEE ALSO
201 Coro, IO::AIO. 154 Linux::Inotify.
202 155
203AUTHOR 156AUTHOR
204 Marc Lehmann <schmorp@schmorp.de> 157 Marc Lehmann <schmorp@schmorp.de>
205 http://home.schmorp.de/ 158 http://home.schmorp.de/
206 159

Diff Legend

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