ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/AIO.pm
(Generate patch)

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.22 by root, Wed Jul 20 21:55:27 2005 UTC vs.
Revision 1.51 by root, Sat Jun 24 19:14:04 2006 UTC

14 aio_unlink "/tmp/file", sub { }; 14 aio_unlink "/tmp/file", sub { };
15 15
16 aio_read $fh, 30000, 1024, $buffer, 0, sub { 16 aio_read $fh, 30000, 1024, $buffer, 0, sub {
17 $_[0] > 0 or die "read error: $!"; 17 $_[0] > 0 or die "read error: $!";
18 }; 18 };
19
20 # AnyEvent
21 open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
22 my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
19 23
20 # Event 24 # Event
21 Event->io (fd => IO::AIO::poll_fileno, 25 Event->io (fd => IO::AIO::poll_fileno,
22 poll => 'r', 26 poll => 'r',
23 cb => \&IO::AIO::poll_cb); 27 cb => \&IO::AIO::poll_cb);
56 60
57=cut 61=cut
58 62
59package IO::AIO; 63package IO::AIO;
60 64
65no warnings;
66use strict 'vars';
67
61use base 'Exporter'; 68use base 'Exporter';
62 69
63use Fcntl ();
64
65BEGIN { 70BEGIN {
66 $VERSION = 0.9; 71 our $VERSION = '1.8';
67 72
68 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink 73 our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
74 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
69 aio_fsync aio_fdatasync aio_readahead); 75 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move);
70 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 76 our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
71 77
72 require XSLoader; 78 require XSLoader;
73 XSLoader::load IO::AIO, $VERSION; 79 XSLoader::load ("IO::AIO", $VERSION);
74} 80}
75 81
76=head1 FUNCTIONS 82=head1 FUNCTIONS
77 83
78=head2 AIO FUNCTIONS 84=head2 AIO FUNCTIONS
83which must be a code reference. This code reference will get called with 89which must be a code reference. This code reference will get called with
84the syscall return code (e.g. most syscalls return C<-1> on error, unlike 90the syscall return code (e.g. most syscalls return C<-1> on error, unlike
85perl, which usually delivers "false") as it's sole argument when the given 91perl, which usually delivers "false") as it's sole argument when the given
86syscall has been executed asynchronously. 92syscall has been executed asynchronously.
87 93
88All functions that expect a filehandle will also accept a file descriptor. 94All functions expecting a filehandle keep a copy of the filehandle
95internally until the request has finished.
89 96
90The filenames you pass to these routines I<must> be absolute. The reason 97The pathnames you pass to these routines I<must> be absolute and
91for this is that at the time the request is being executed, the current 98encoded in byte form. The reason for the former is that at the time the
92working directory could have changed. Alternatively, you can make sure 99request is being executed, the current working directory could have
93that you never change the current working directory. 100changed. Alternatively, you can make sure that you never change the
101current working directory.
102
103To encode pathnames to byte form, either make sure you either: a)
104always pass in filenames you got from outside (command line, readdir
105etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and encode
106your pathnames to the locale (or other) encoding in effect in the user
107environment, d) use Glib::filename_from_unicode on unicode filenames or e)
108use something else.
94 109
95=over 4 110=over 4
96 111
97=item aio_open $pathname, $flags, $mode, $callback 112=item aio_open $pathname, $flags, $mode, $callback->($fh)
98 113
99Asynchronously open or create a file and call the callback with a newly 114Asynchronously open or create a file and call the callback with a newly
100created filehandle for the file. 115created filehandle for the file.
101 116
102The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 117The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
119 } else { 134 } else {
120 die "open failed: $!\n"; 135 die "open failed: $!\n";
121 } 136 }
122 }; 137 };
123 138
124=item aio_close $fh, $callback 139=item aio_close $fh, $callback->($status)
125 140
126Asynchronously close a file and call the callback with the result 141Asynchronously close a file and call the callback with the result
127code. I<WARNING:> although accepted, you should not pass in a perl 142code. I<WARNING:> although accepted, you should not pass in a perl
128filehandle here, as perl will likely close the file descriptor another 143filehandle here, as perl will likely close the file descriptor another
129time when the filehandle is destroyed. Normally, you can safely call perls 144time when the filehandle is destroyed. Normally, you can safely call perls
130C<close> or just let filehandles go out of scope. 145C<close> or just let filehandles go out of scope.
131 146
132This is supposed to be a bug in the API, so that might change. It's 147This is supposed to be a bug in the API, so that might change. It's
133therefore best to avoid this function. 148therefore best to avoid this function.
134 149
135=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback 150=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
136 151
137=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback 152=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
138 153
139Reads or writes C<length> bytes from the specified C<fh> and C<offset> 154Reads or writes C<length> bytes from the specified C<fh> and C<offset>
140into the scalar given by C<data> and offset C<dataoffset> and calls the 155into the scalar given by C<data> and offset C<dataoffset> and calls the
141callback without the actual number of bytes read (or -1 on error, just 156callback without the actual number of bytes read (or -1 on error, just
142like the syscall). 157like the syscall).
143 158
159The C<$data> scalar I<MUST NOT> be modified in any way while the request
160is outstanding. Modifying it can result in segfaults or WW3 (if the
161necessary/optional hardware is installed).
162
144Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at 163Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at
145offset C<0> within the scalar: 164offset C<0> within the scalar:
146 165
147 aio_read $fh, 7, 15, $buffer, 0, sub { 166 aio_read $fh, 7, 15, $buffer, 0, sub {
148 $_[0] > 0 or die "read error: $!"; 167 $_[0] > 0 or die "read error: $!";
149 print "read $_[0] bytes: <$buffer>\n"; 168 print "read $_[0] bytes: <$buffer>\n";
150 }; 169 };
151 170
171=item aio_move $srcpath, $dstpath, $callback->($status)
172
173[EXPERIMENTAL]
174
175Try to move the I<file> (directories not supported as either source or destination)
176from C<$srcpath> to C<$dstpath> and call the callback with the C<0> (error) or C<-1> ok.
177
178This is a composite request that tries to rename(2) the file first. If
179rename files with C<EXDEV>, it creates the destination file with mode 0200
180and copies the contents of the source file into it using C<aio_sendfile>,
181followed by restoring atime, mtime, access mode and uid/gid, in that
182order, and unlinking the C<$srcpath>.
183
184If an error occurs, the partial destination file will be unlinked, if
185possible, except when setting atime, mtime, access mode and uid/gid, where
186errors are being ignored.
187
188=cut
189
190sub aio_move($$$) {
191 my ($src, $dst, $cb) = @_;
192
193 aio_rename $src, $dst, sub {
194 if ($_[0] && $! == EXDEV) {
195 aio_open $src, O_RDONLY, 0, sub {
196 if (my $src_fh = $_[0]) {
197 my @stat = stat $src_fh;
198
199 aio_open $dst, O_WRONLY, 0200, sub {
200 if (my $dst_fh = $_[0]) {
201 aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
202 close $src_fh;
203
204 if ($_[0] == $stat[7]) {
205 utime $stat[8], $stat[9], $dst;
206 chmod $stat[2] & 07777, $dst_fh;
207 chown $stat[4], $stat[5], $dst_fh;
208 close $dst_fh;
209
210 aio_unlink $src, sub {
211 $cb->($_[0]);
212 };
213 } else {
214 my $errno = $!;
215 aio_unlink $dst, sub {
216 $! = $errno;
217 $cb->(-1);
218 };
219 }
220 };
221 } else {
222 $cb->(-1);
223 }
224 },
225
226 } else {
227 $cb->(-1);
228 }
229 };
230 } else {
231 $cb->($_[0]);
232 }
233 };
234}
235
236=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
237
238Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
239reading at byte offset C<$in_offset>, and starts writing at the current
240file offset of C<$out_fh>. Because of that, it is not safe to issue more
241than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
242other.
243
244This call tries to make use of a native C<sendfile> syscall to provide
245zero-copy operation. For this to work, C<$out_fh> should refer to a
246socket, and C<$in_fh> should refer to mmap'able file.
247
248If the native sendfile call fails or is not implemented, it will be
249emulated, so you can call C<aio_sendfile> on any type of filehandle
250regardless of the limitations of the operating system.
251
252Please note, however, that C<aio_sendfile> can read more bytes from
253C<$in_fh> than are written, and there is no way to find out how many
254bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
255provides the number of bytes written to C<$out_fh>. Only if the result
256value equals C<$length> one can assume that C<$length> bytes have been
257read.
258
152=item aio_readahead $fh,$offset,$length, $callback 259=item aio_readahead $fh,$offset,$length, $callback->($retval)
153
154Asynchronously reads the specified byte range into the page cache, using
155the C<readahead> syscall. If that syscall doesn't exist (likely if your OS
156isn't Linux) the status will be C<-1> and C<$!> is set to C<ENOSYS>.
157 260
158C<aio_readahead> populates the page cache with data from a file so that 261C<aio_readahead> populates the page cache with data from a file so that
159subsequent reads from that file will not block on disk I/O. The C<$offset> 262subsequent reads from that file will not block on disk I/O. The C<$offset>
160argument specifies the starting point from which data is to be read and 263argument specifies the starting point from which data is to be read and
161C<$length> specifies the number of bytes to be read. I/O is performed in 264C<$length> specifies the number of bytes to be read. I/O is performed in
162whole pages, so that offset is effectively rounded down to a page boundary 265whole pages, so that offset is effectively rounded down to a page boundary
163and bytes are read up to the next page boundary greater than or equal to 266and bytes are read up to the next page boundary greater than or equal to
164(off-set+length). C<aio_readahead> does not read beyond the end of the 267(off-set+length). C<aio_readahead> does not read beyond the end of the
165file. The current file offset of the file is left unchanged. 268file. The current file offset of the file is left unchanged.
166 269
270If that syscall doesn't exist (likely if your OS isn't Linux) it will be
271emulated by simply reading the data, which would have a similar effect.
272
167=item aio_stat $fh_or_path, $callback 273=item aio_stat $fh_or_path, $callback->($status)
168 274
169=item aio_lstat $fh, $callback 275=item aio_lstat $fh, $callback->($status)
170 276
171Works like perl's C<stat> or C<lstat> in void context. The callback will 277Works like perl's C<stat> or C<lstat> in void context. The callback will
172be called after the stat and the results will be available using C<stat _> 278be called after the stat and the results will be available using C<stat _>
173or C<-s _> etc... 279or C<-s _> etc...
174 280
184 aio_stat "/etc/passwd", sub { 290 aio_stat "/etc/passwd", sub {
185 $_[0] and die "stat failed: $!"; 291 $_[0] and die "stat failed: $!";
186 print "size is ", -s _, "\n"; 292 print "size is ", -s _, "\n";
187 }; 293 };
188 294
189=item aio_unlink $pathname, $callback 295=item aio_unlink $pathname, $callback->($status)
190 296
191Asynchronously unlink (delete) a file and call the callback with the 297Asynchronously unlink (delete) a file and call the callback with the
192result code. 298result code.
193 299
300=item aio_link $srcpath, $dstpath, $callback->($status)
301
302Asynchronously create a new link to the existing object at C<$srcpath> at
303the path C<$dstpath> and call the callback with the result code.
304
305=item aio_symlink $srcpath, $dstpath, $callback->($status)
306
307Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
308the path C<$dstpath> and call the callback with the result code.
309
310=item aio_rename $srcpath, $dstpath, $callback->($status)
311
312Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
313rename(2) and call the callback with the result code.
314
315=item aio_rmdir $pathname, $callback->($status)
316
317Asynchronously rmdir (delete) a directory and call the callback with the
318result code.
319
320=item aio_readdir $pathname, $callback->($entries)
321
322Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
323directory (i.e. opendir + readdir + closedir). The entries will not be
324sorted, and will B<NOT> include the C<.> and C<..> entries.
325
326The callback a single argument which is either C<undef> or an array-ref
327with the filenames.
328
329=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
330
331Scans a directory (similar to C<aio_readdir>) and tries to separate the
332entries of directory C<$path> into two sets of names, ones you can recurse
333into (directories), and ones you cannot recurse into (everything else).
334
335C<aio_scandir> is a composite request that consists of many
336aio-primitives. C<$maxreq> specifies the maximum number of outstanding
337aio requests that this function generates. If it is C<< <= 0 >>, then a
338suitable default will be chosen (currently 8).
339
340On error, the callback is called without arguments, otherwise it receives
341two array-refs with path-relative entry names.
342
343Example:
344
345 aio_scandir $dir, 0, sub {
346 my ($dirs, $nondirs) = @_;
347 print "real directories: @$dirs\n";
348 print "everything else: @$nondirs\n";
349 };
350
351Implementation notes.
352
353The C<aio_readdir> cannot be avoided, but C<stat()>'ing every entry can.
354
355After reading the directory, the modification time, size etc. of the
356directory before and after the readdir is checked, and if they match, the
357link count will be used to decide how many entries are directories (if
358>= 2). Otherwise, no knowledge of the number of subdirectories will be
359assumed.
360
361Then entires will be sorted into likely directories (everything without a
362non-initial dot) and likely non-directories (everything else). Then every
363entry + C</.> will be C<stat>'ed, likely directories first. This is often
364faster because filesystems might detect the type of the entry without
365reading the inode data (e.g. ext2fs filetype feature). If that succeeds,
366it assumes that the entry is a directory or a symlink to directory (which
367will be checked seperately).
368
369If the known number of directories has been reached, the rest of the
370entries is assumed to be non-directories.
371
372=cut
373
374sub aio_scandir($$$) {
375 my ($path, $maxreq, $cb) = @_;
376
377 $maxreq = 8 if $maxreq <= 0;
378
379 # stat once
380 aio_stat $path, sub {
381 return $cb->() if $_[0];
382 my $hash1 = join ":", (stat _)[0,1,3,7,9];
383
384 # read the directory entries
385 aio_readdir $path, sub {
386 my $entries = shift
387 or return $cb->();
388
389 # stat the dir another time
390 aio_stat $path, sub {
391 my $hash2 = join ":", (stat _)[0,1,3,7,9];
392
393 my $ndirs;
394
395 # take the slow route if anything looks fishy
396 if ($hash1 ne $hash2) {
397 $ndirs = -1;
398 } else {
399 # if nlink == 2, we are finished
400 # on non-posix-fs's, we rely on nlink < 2
401 $ndirs = (stat _)[3] - 2
402 or return $cb->([], $entries);
403 }
404
405 # sort into likely dirs and likely nondirs
406 # dirs == files without ".", short entries first
407 $entries = [map $_->[0],
408 sort { $b->[1] cmp $a->[1] }
409 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
410 @$entries];
411
412 my (@dirs, @nondirs);
413
414 my ($statcb, $schedcb);
415 my $nreq = 0;
416
417 $schedcb = sub {
418 if (@$entries) {
419 if ($nreq < $maxreq) {
420 my $ent = pop @$entries;
421 $nreq++;
422 aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) };
423 }
424 } elsif (!$nreq) {
425 # finished
426 undef $statcb;
427 undef $schedcb;
428 $cb->(\@dirs, \@nondirs) if $cb;
429 undef $cb;
430 }
431 };
432 $statcb = sub {
433 my ($status, $entry) = @_;
434
435 if ($status < 0) {
436 $nreq--;
437 push @nondirs, $entry;
438 &$schedcb;
439 } else {
440 # need to check for real directory
441 aio_lstat "$path/$entry", sub {
442 $nreq--;
443
444 if (-d _) {
445 push @dirs, $entry;
446
447 if (!--$ndirs) {
448 push @nondirs, @$entries;
449 $entries = [];
450 }
451 } else {
452 push @nondirs, $entry;
453 }
454
455 &$schedcb;
456 }
457 }
458 };
459
460 &$schedcb while @$entries && $nreq < $maxreq;
461 };
462 };
463 };
464}
465
194=item aio_fsync $fh, $callback 466=item aio_fsync $fh, $callback->($status)
195 467
196Asynchronously call fsync on the given filehandle and call the callback 468Asynchronously call fsync on the given filehandle and call the callback
197with the fsync result code. 469with the fsync result code.
198 470
199=item aio_fdatasync $fh, $callback 471=item aio_fdatasync $fh, $callback->($status)
200 472
201Asynchronously call fdatasync on the given filehandle and call the 473Asynchronously call fdatasync on the given filehandle and call the
202callback with the fdatasync result code. Might set C<$!> to C<ENOSYS> if 474callback with the fdatasync result code.
203C<fdatasync> is not available. 475
476If this call isn't available because your OS lacks it or it couldn't be
477detected, it will be emulated by calling C<fsync> instead.
204 478
205=back 479=back
206 480
207=head2 SUPPORT FUNCTIONS 481=head2 SUPPORT FUNCTIONS
208 482
266 IO::AIO::poll_wait, IO::AIO::poll_cb 540 IO::AIO::poll_wait, IO::AIO::poll_cb
267 if IO::AIO::nreqs; 541 if IO::AIO::nreqs;
268 542
269=item IO::AIO::min_parallel $nthreads 543=item IO::AIO::min_parallel $nthreads
270 544
271Set the minimum number of AIO threads to C<$nthreads>. The default is 545Set the minimum number of AIO threads to C<$nthreads>. The current default
272C<1>, which means a single asynchronous operation can be done at one time 546is C<4>, which means four asynchronous operations can be done at one time
273(the number of outstanding operations, however, is unlimited). 547(the number of outstanding operations, however, is unlimited).
548
549IO::AIO starts threads only on demand, when an AIO request is queued and
550no free thread exists.
274 551
275It is recommended to keep the number of threads low, as some Linux 552It is recommended to keep the number of threads low, as some Linux
276kernel versions will scale negatively with the number of threads (higher 553kernel versions will scale negatively with the number of threads (higher
277parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 554parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
278threads should be fine. 555threads should be fine.
279 556
280Under normal circumstances you don't need to call this function, as this 557Under most circumstances you don't need to call this function, as the
281module automatically starts some threads (the exact number might change, 558module selects a default that is suitable for low to moderate load.
282and is currently 4).
283 559
284=item IO::AIO::max_parallel $nthreads 560=item IO::AIO::max_parallel $nthreads
285 561
286Sets the maximum number of AIO threads to C<$nthreads>. If more than 562Sets the maximum number of AIO threads to C<$nthreads>. If more than the
287the specified number of threads are currently running, kill them. This 563specified number of threads are currently running, this function kills
288function blocks until the limit is reached. 564them. This function blocks until the limit is reached.
565
566While C<$nthreads> are zero, aio requests get queued but not executed
567until the number of threads has been increased again.
289 568
290This module automatically runs C<max_parallel 0> at program end, to ensure 569This module automatically runs C<max_parallel 0> at program end, to ensure
291that all threads are killed and that there are no outstanding requests. 570that all threads are killed and that there are no outstanding requests.
292 571
293Under normal circumstances you don't need to call this function. 572Under normal circumstances you don't need to call this function.
297Sets the maximum number of outstanding requests to C<$nreqs>. If you 576Sets the maximum number of outstanding requests to C<$nreqs>. If you
298try to queue up more than this number of requests, the caller will block until 577try to queue up more than this number of requests, the caller will block until
299some requests have been handled. 578some requests have been handled.
300 579
301The default is very large, so normally there is no practical limit. If you 580The default is very large, so normally there is no practical limit. If you
302queue up many requests in a loop it it often improves speed if you set 581queue up many requests in a loop it often improves speed if you set
303this to a relatively low number, such as C<100>. 582this to a relatively low number, such as C<100>.
304 583
305Under normal circumstances you don't need to call this function. 584Under normal circumstances you don't need to call this function.
306 585
307=back 586=back
310 589
311# support function to convert a fd into a perl filehandle 590# support function to convert a fd into a perl filehandle
312sub _fd2fh { 591sub _fd2fh {
313 return undef if $_[0] < 0; 592 return undef if $_[0] < 0;
314 593
315 # try to be perl5.6-compatible 594 # try to generate nice filehandles
316 local *AIO_FH; 595 my $sym = "IO::AIO::fd#$_[0]";
317 open AIO_FH, "+<&=$_[0]" 596 local *$sym;
597
598 open *$sym, "+<&=$_[0]" # usually works under any unix
599 or open *$sym, "<&=$_[0]" # cygwin needs this
600 or open *$sym, ">&=$_[0]" # or this
318 or return undef; 601 or return undef;
319 602
320 *AIO_FH 603 *$sym
321} 604}
322 605
323min_parallel 4; 606min_parallel 4;
324 607
325END { 608END {
326 max_parallel 0; 609 max_parallel 0;
327} 610}
328 611
3291; 6121;
330 613
614=head2 FORK BEHAVIOUR
615
616Before the fork, IO::AIO enters a quiescent state where no requests
617can be added in other threads and no results will be processed. After
618the fork the parent simply leaves the quiescent state and continues
619request/result processing, while the child clears the request/result
620queue (so the requests started before the fork will only be handled in
621the parent). Threats will be started on demand until the limit ste in the
622parent process has been reached again.
623
331=head1 SEE ALSO 624=head1 SEE ALSO
332 625
333L<Coro>, L<Linux::AIO>. 626L<Coro>, L<Linux::AIO>.
334 627
335=head1 AUTHOR 628=head1 AUTHOR

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines