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.100 by root, Sun Jan 7 21:36:58 2007 UTC vs.
Revision 1.130 by root, Thu Jun 19 21:25:30 2008 UTC

… …
26 $req->cancel; # cancel request if still in queue 26 $req->cancel; # cancel request if still in queue
27 27
28 my $grp = aio_group sub { print "all stats done\n" }; 28 my $grp = aio_group sub { print "all stats done\n" };
29 add $grp aio_stat "..." for ...; 29 add $grp aio_stat "..." for ...;
30 30
31 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
32 use AnyEvent::AIO;
33
31 # AnyEvent integration 34 # EV integration
32 open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!"; 35 my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
33 my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
34 36
35 # Event integration 37 # Event integration
36 Event->io (fd => IO::AIO::poll_fileno, 38 Event->io (fd => IO::AIO::poll_fileno,
37 poll => 'r', 39 poll => 'r',
38 cb => \&IO::AIO::poll_cb); 40 cb => \&IO::AIO::poll_cb);
… …
62etc.), but can also be used to easily do operations in parallel that are 64etc.), but can also be used to easily do operations in parallel that are
63normally done sequentially, e.g. stat'ing many files, which is much faster 65normally done sequentially, e.g. stat'ing many files, which is much faster
64on a RAID volume or over NFS when you do a number of stat operations 66on a RAID volume or over NFS when you do a number of stat operations
65concurrently. 67concurrently.
66 68
67While most of this works on all types of file descriptors (for example 69While most of this works on all types of file descriptors (for
68sockets), using these functions on file descriptors that support 70example sockets), using these functions on file descriptors that
69nonblocking operation (again, sockets, pipes etc.) is very inefficient or 71support nonblocking operation (again, sockets, pipes etc.) is very
70might not work (aio_read fails on sockets/pipes/fifos). Use an event loop 72inefficient. Use an event loop for that (such as the L<Event|Event>
71for that (such as the L<Event|Event> module): IO::AIO will naturally fit 73module): IO::AIO will naturally fit into such an event loop itself.
72into such an event loop itself.
73 74
74In this version, a number of threads are started that execute your 75In this version, a number of threads are started that execute your
75requests and signal their completion. You don't need thread support 76requests and signal their completion. You don't need thread support
76in perl, and the threads created by this module will not be visible 77in perl, and the threads created by this module will not be visible
77to perl. In the future, this module might make use of the native aio 78to perl. In the future, this module might make use of the native aio
… …
79not well-supported or restricted (GNU/Linux doesn't allow them on normal 80not well-supported or restricted (GNU/Linux doesn't allow them on normal
80files currently, for example), and they would only support aio_read and 81files currently, for example), and they would only support aio_read and
81aio_write, so the remaining functionality would have to be implemented 82aio_write, so the remaining functionality would have to be implemented
82using threads anyway. 83using threads anyway.
83 84
84Although the module will work with in the presence of other (Perl-) 85Although the module will work in the presence of other (Perl-) threads,
85threads, it is currently not reentrant in any way, so use appropriate 86it is currently not reentrant in any way, so use appropriate locking
86locking yourself, always call C<poll_cb> from within the same thread, or 87yourself, always call C<poll_cb> from within the same thread, or never
87never call C<poll_cb> (or other C<aio_> functions) recursively. 88call C<poll_cb> (or other C<aio_> functions) recursively.
88 89
89=head2 EXAMPLE 90=head2 EXAMPLE
90 91
91This is a simple example that uses the Event module and loads 92This is a simple example that uses the Event module and loads
92F</etc/passwd> asynchronously: 93F</etc/passwd> asynchronously:
… …
184 185
185=cut 186=cut
186 187
187package IO::AIO; 188package IO::AIO;
188 189
190use Carp ();
191
189no warnings; 192no warnings;
190use strict 'vars'; 193use strict 'vars';
191 194
192use base 'Exporter'; 195use base 'Exporter';
193 196
194BEGIN { 197BEGIN {
195 our $VERSION = '2.32'; 198 our $VERSION = '3.05';
196 199
197 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat 200 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
198 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink 201 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir
199 aio_readlink aio_fsync aio_fdatasync aio_readahead aio_rename aio_link 202 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync
200 aio_move aio_copy aio_group aio_nop aio_mknod aio_load aio_rmtree); 203 aio_fdatasync aio_pathsync aio_readahead
204 aio_rename aio_link aio_move aio_copy aio_group
205 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
206 aio_chmod aio_utime aio_truncate);
207
201 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice aio_block)); 208 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
202 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 209 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
203 min_parallel max_parallel max_idle 210 min_parallel max_parallel max_idle
204 nreqs nready npending nthreads 211 nreqs nready npending nthreads
205 max_poll_time max_poll_reqs); 212 max_poll_time max_poll_reqs);
206 213
… …
271 aio_read $_[0], ..., sub { 278 aio_read $_[0], ..., sub {
272 ... 279 ...
273 }; 280 };
274 }; 281 };
275 282
283
276=item aioreq_nice $pri_adjust 284=item aioreq_nice $pri_adjust
277 285
278Similar to C<aioreq_pri>, but subtracts the given value from the current 286Similar to C<aioreq_pri>, but subtracts the given value from the current
279priority, so the effect is cumulative. 287priority, so the effect is cumulative.
288
280 289
281=item aio_open $pathname, $flags, $mode, $callback->($fh) 290=item aio_open $pathname, $flags, $mode, $callback->($fh)
282 291
283Asynchronously open or create a file and call the callback with a newly 292Asynchronously open or create a file and call the callback with a newly
284created filehandle for the file. 293created filehandle for the file.
… …
290list. They are the same as used by C<sysopen>. 299list. They are the same as used by C<sysopen>.
291 300
292Likewise, C<$mode> specifies the mode of the newly created file, if it 301Likewise, C<$mode> specifies the mode of the newly created file, if it
293didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>, 302didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
294except that it is mandatory (i.e. use C<0> if you don't create new files, 303except that it is mandatory (i.e. use C<0> if you don't create new files,
295and C<0666> or C<0777> if you do). 304and C<0666> or C<0777> if you do). Note that the C<$mode> will be modified
305by the umask in effect then the request is being executed, so better never
306change the umask.
296 307
297Example: 308Example:
298 309
299 aio_open "/etc/passwd", O_RDONLY, 0, sub { 310 aio_open "/etc/passwd", O_RDONLY, 0, sub {
300 if ($_[0]) { 311 if ($_[0]) {
… …
303 } else { 314 } else {
304 die "open failed: $!\n"; 315 die "open failed: $!\n";
305 } 316 }
306 }; 317 };
307 318
319
308=item aio_close $fh, $callback->($status) 320=item aio_close $fh, $callback->($status)
309 321
310Asynchronously close a file and call the callback with the result 322Asynchronously close a file and call the callback with the result
311code. I<WARNING:> although accepted, you should not pass in a perl 323code.
312filehandle here, as perl will likely close the file descriptor another
313time when the filehandle is destroyed. Normally, you can safely call perls
314C<close> or just let filehandles go out of scope.
315 324
316This is supposed to be a bug in the API, so that might change. It's 325Unfortunately, you can't do this to perl. Perl I<insists> very strongly on
317therefore best to avoid this function. 326closing the file descriptor associated with the filehandle itself.
327
328Therefore, C<aio_close> will not close the filehandle - instead it will
329use dup2 to overwrite the file descriptor with the write-end of a pipe
330(the pipe fd will be created on demand and will be cached).
331
332Or in other words: the file descriptor will be closed, but it will not be
333free for reuse until the perl filehandle is closed.
334
335=cut
318 336
319=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 337=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
320 338
321=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 339=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
322 340
323Reads or writes C<length> bytes from the specified C<fh> and C<offset> 341Reads or writes C<$length> bytes from the specified C<$fh> and C<$offset>
324into the scalar given by C<data> and offset C<dataoffset> and calls the 342into the scalar given by C<$data> and offset C<$dataoffset> and calls the
325callback without the actual number of bytes read (or -1 on error, just 343callback without the actual number of bytes read (or -1 on error, just
326like the syscall). 344like the syscall).
327 345
346If C<$offset> is undefined, then the current file descriptor offset will
347be used (and updated), otherwise the file descriptor offset will not be
348changed by these calls.
349
350If C<$length> is undefined in C<aio_write>, use the remaining length of C<$data>.
351
352If C<$dataoffset> is less than zero, it will be counted from the end of
353C<$data>.
354
328The C<$data> scalar I<MUST NOT> be modified in any way while the request 355The C<$data> scalar I<MUST NOT> be modified in any way while the request
329is outstanding. Modifying it can result in segfaults or WW3 (if the 356is outstanding. Modifying it can result in segfaults or World War III (if
330necessary/optional hardware is installed). 357the necessary/optional hardware is installed).
331 358
332Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at 359Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at
333offset C<0> within the scalar: 360offset C<0> within the scalar:
334 361
335 aio_read $fh, 7, 15, $buffer, 0, sub { 362 aio_read $fh, 7, 15, $buffer, 0, sub {
336 $_[0] > 0 or die "read error: $!"; 363 $_[0] > 0 or die "read error: $!";
337 print "read $_[0] bytes: <$buffer>\n"; 364 print "read $_[0] bytes: <$buffer>\n";
338 }; 365 };
366
339 367
340=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 368=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
341 369
342Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts 370Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
343reading at byte offset C<$in_offset>, and starts writing at the current 371reading at byte offset C<$in_offset>, and starts writing at the current
… …
357C<$in_fh> than are written, and there is no way to find out how many 385C<$in_fh> than are written, and there is no way to find out how many
358bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only 386bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
359provides the number of bytes written to C<$out_fh>. Only if the result 387provides the number of bytes written to C<$out_fh>. Only if the result
360value equals C<$length> one can assume that C<$length> bytes have been 388value equals C<$length> one can assume that C<$length> bytes have been
361read. 389read.
390
362 391
363=item aio_readahead $fh,$offset,$length, $callback->($retval) 392=item aio_readahead $fh,$offset,$length, $callback->($retval)
364 393
365C<aio_readahead> populates the page cache with data from a file so that 394C<aio_readahead> populates the page cache with data from a file so that
366subsequent reads from that file will not block on disk I/O. The C<$offset> 395subsequent reads from that file will not block on disk I/O. The C<$offset>
… …
372file. The current file offset of the file is left unchanged. 401file. The current file offset of the file is left unchanged.
373 402
374If that syscall doesn't exist (likely if your OS isn't Linux) it will be 403If that syscall doesn't exist (likely if your OS isn't Linux) it will be
375emulated by simply reading the data, which would have a similar effect. 404emulated by simply reading the data, which would have a similar effect.
376 405
406
377=item aio_stat $fh_or_path, $callback->($status) 407=item aio_stat $fh_or_path, $callback->($status)
378 408
379=item aio_lstat $fh, $callback->($status) 409=item aio_lstat $fh, $callback->($status)
380 410
381Works like perl's C<stat> or C<lstat> in void context. The callback will 411Works like perl's C<stat> or C<lstat> in void context. The callback will
… …
394 aio_stat "/etc/passwd", sub { 424 aio_stat "/etc/passwd", sub {
395 $_[0] and die "stat failed: $!"; 425 $_[0] and die "stat failed: $!";
396 print "size is ", -s _, "\n"; 426 print "size is ", -s _, "\n";
397 }; 427 };
398 428
429
430=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
431
432Works like perl's C<utime> function (including the special case of $atime
433and $mtime being undef). Fractional times are supported if the underlying
434syscalls support them.
435
436When called with a pathname, uses utimes(2) if available, otherwise
437utime(2). If called on a file descriptor, uses futimes(2) if available,
438otherwise returns ENOSYS, so this is not portable.
439
440Examples:
441
442 # set atime and mtime to current time (basically touch(1)):
443 aio_utime "path", undef, undef;
444 # set atime to current time and mtime to beginning of the epoch:
445 aio_utime "path", time, undef; # undef==0
446
447
448=item aio_chown $fh_or_path, $uid, $gid, $callback->($status)
449
450Works like perl's C<chown> function, except that C<undef> for either $uid
451or $gid is being interpreted as "do not change" (but -1 can also be used).
452
453Examples:
454
455 # same as "chown root path" in the shell:
456 aio_chown "path", 0, -1;
457 # same as above:
458 aio_chown "path", 0, undef;
459
460
461=item aio_truncate $fh_or_path, $offset, $callback->($status)
462
463Works like truncate(2) or ftruncate(2).
464
465
466=item aio_chmod $fh_or_path, $mode, $callback->($status)
467
468Works like perl's C<chmod> function.
469
470
399=item aio_unlink $pathname, $callback->($status) 471=item aio_unlink $pathname, $callback->($status)
400 472
401Asynchronously unlink (delete) a file and call the callback with the 473Asynchronously unlink (delete) a file and call the callback with the
402result code. 474result code.
403 475
476
404=item aio_mknod $path, $mode, $dev, $callback->($status) 477=item aio_mknod $path, $mode, $dev, $callback->($status)
405 478
406[EXPERIMENTAL] 479[EXPERIMENTAL]
407 480
408Asynchronously create a device node (or fifo). See mknod(2). 481Asynchronously create a device node (or fifo). See mknod(2).
409 482
410The only (POSIX-) portable way of calling this function is: 483The only (POSIX-) portable way of calling this function is:
411 484
412 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 485 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
486
413 487
414=item aio_link $srcpath, $dstpath, $callback->($status) 488=item aio_link $srcpath, $dstpath, $callback->($status)
415 489
416Asynchronously create a new link to the existing object at C<$srcpath> at 490Asynchronously create a new link to the existing object at C<$srcpath> at
417the path C<$dstpath> and call the callback with the result code. 491the path C<$dstpath> and call the callback with the result code.
418 492
493
419=item aio_symlink $srcpath, $dstpath, $callback->($status) 494=item aio_symlink $srcpath, $dstpath, $callback->($status)
420 495
421Asynchronously create a new symbolic link to the existing object at C<$srcpath> at 496Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
422the path C<$dstpath> and call the callback with the result code. 497the path C<$dstpath> and call the callback with the result code.
498
423 499
424=item aio_readlink $path, $callback->($link) 500=item aio_readlink $path, $callback->($link)
425 501
426Asynchronously read the symlink specified by C<$path> and pass it to 502Asynchronously read the symlink specified by C<$path> and pass it to
427the callback. If an error occurs, nothing or undef gets passed to the 503the callback. If an error occurs, nothing or undef gets passed to the
428callback. 504callback.
429 505
506
430=item aio_rename $srcpath, $dstpath, $callback->($status) 507=item aio_rename $srcpath, $dstpath, $callback->($status)
431 508
432Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 509Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
433rename(2) and call the callback with the result code. 510rename(2) and call the callback with the result code.
434 511
512
513=item aio_mkdir $pathname, $mode, $callback->($status)
514
515Asynchronously mkdir (create) a directory and call the callback with
516the result code. C<$mode> will be modified by the umask at the time the
517request is executed, so do not change your umask.
518
519
435=item aio_rmdir $pathname, $callback->($status) 520=item aio_rmdir $pathname, $callback->($status)
436 521
437Asynchronously rmdir (delete) a directory and call the callback with the 522Asynchronously rmdir (delete) a directory and call the callback with the
438result code. 523result code.
524
439 525
440=item aio_readdir $pathname, $callback->($entries) 526=item aio_readdir $pathname, $callback->($entries)
441 527
442Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 528Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
443directory (i.e. opendir + readdir + closedir). The entries will not be 529directory (i.e. opendir + readdir + closedir). The entries will not be
444sorted, and will B<NOT> include the C<.> and C<..> entries. 530sorted, and will B<NOT> include the C<.> and C<..> entries.
445 531
446The callback a single argument which is either C<undef> or an array-ref 532The callback a single argument which is either C<undef> or an array-ref
447with the filenames. 533with the filenames.
448 534
535
449=item aio_load $path, $data, $callback->($status) 536=item aio_load $path, $data, $callback->($status)
450 537
451This is a composite request that tries to fully load the given file into 538This is a composite request that tries to fully load the given file into
452memory. Status is the same as with aio_read. 539memory. Status is the same as with aio_read.
453 540
454=cut 541=cut
455 542
456sub aio_load($$;$) { 543sub aio_load($$;$) {
457 aio_block {
458 my ($path, undef, $cb) = @_; 544 my ($path, undef, $cb) = @_;
459 my $data = \$_[1]; 545 my $data = \$_[1];
460 546
461 my $pri = aioreq_pri; 547 my $pri = aioreq_pri;
462 my $grp = aio_group $cb; 548 my $grp = aio_group $cb;
549
550 aioreq_pri $pri;
551 add $grp aio_open $path, O_RDONLY, 0, sub {
552 my $fh = shift
553 or return $grp->result (-1);
463 554
464 aioreq_pri $pri; 555 aioreq_pri $pri;
465 add $grp aio_open $path, O_RDONLY, 0, sub {
466 my ($fh) = @_
467 or return $grp->result (-1);
468
469 aioreq_pri $pri;
470 add $grp aio_read $fh, 0, (-s $fh), $$data, 0, sub { 556 add $grp aio_read $fh, 0, (-s $fh), $$data, 0, sub {
471 $grp->result ($_[0]); 557 $grp->result ($_[0]);
472 };
473 }; 558 };
474
475 $grp
476 } 559 };
560
561 $grp
477} 562}
478 563
479=item aio_copy $srcpath, $dstpath, $callback->($status) 564=item aio_copy $srcpath, $dstpath, $callback->($status)
480 565
481Try to copy the I<file> (directories not supported as either source or 566Try to copy the I<file> (directories not supported as either source or
… …
492errors are being ignored. 577errors are being ignored.
493 578
494=cut 579=cut
495 580
496sub aio_copy($$;$) { 581sub aio_copy($$;$) {
497 aio_block {
498 my ($src, $dst, $cb) = @_; 582 my ($src, $dst, $cb) = @_;
499 583
500 my $pri = aioreq_pri; 584 my $pri = aioreq_pri;
501 my $grp = aio_group $cb; 585 my $grp = aio_group $cb;
502 586
503 aioreq_pri $pri; 587 aioreq_pri $pri;
504 add $grp aio_open $src, O_RDONLY, 0, sub { 588 add $grp aio_open $src, O_RDONLY, 0, sub {
505 if (my $src_fh = $_[0]) { 589 if (my $src_fh = $_[0]) {
506 my @stat = stat $src_fh; 590 my @stat = stat $src_fh;
507 591
508 aioreq_pri $pri; 592 aioreq_pri $pri;
509 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub { 593 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
510 if (my $dst_fh = $_[0]) { 594 if (my $dst_fh = $_[0]) {
511 aioreq_pri $pri; 595 aioreq_pri $pri;
512 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub { 596 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
513 if ($_[0] == $stat[7]) { 597 if ($_[0] == $stat[7]) {
514 $grp->result (0); 598 $grp->result (0);
515 close $src_fh; 599 close $src_fh;
516 600
517 # those should not normally block. should. should. 601 # those should not normally block. should. should.
518 utime $stat[8], $stat[9], $dst; 602 utime $stat[8], $stat[9], $dst;
519 chmod $stat[2] & 07777, $dst_fh; 603 chmod $stat[2] & 07777, $dst_fh;
520 chown $stat[4], $stat[5], $dst_fh; 604 chown $stat[4], $stat[5], $dst_fh;
605
606 aioreq_pri $pri;
521 close $dst_fh; 607 add $grp aio_close $dst_fh;
522 } else { 608 } else {
523 $grp->result (-1); 609 $grp->result (-1);
524 close $src_fh; 610 close $src_fh;
525 close $dst_fh; 611 close $dst_fh;
526 612
527 aioreq $pri; 613 aioreq $pri;
528 add $grp aio_unlink $dst; 614 add $grp aio_unlink $dst;
529 }
530 }; 615 }
531 } else {
532 $grp->result (-1);
533 } 616 };
617 } else {
618 $grp->result (-1);
534 }, 619 }
535
536 } else {
537 $grp->result (-1);
538 } 620 },
621
622 } else {
623 $grp->result (-1);
539 }; 624 }
540
541 $grp
542 } 625 };
626
627 $grp
543} 628}
544 629
545=item aio_move $srcpath, $dstpath, $callback->($status) 630=item aio_move $srcpath, $dstpath, $callback->($status)
546 631
547Try to move the I<file> (directories not supported as either source or 632Try to move the I<file> (directories not supported as either source or
… …
553that is successful, unlinking the C<$srcpath>. 638that is successful, unlinking the C<$srcpath>.
554 639
555=cut 640=cut
556 641
557sub aio_move($$;$) { 642sub aio_move($$;$) {
558 aio_block {
559 my ($src, $dst, $cb) = @_; 643 my ($src, $dst, $cb) = @_;
560 644
561 my $pri = aioreq_pri; 645 my $pri = aioreq_pri;
562 my $grp = aio_group $cb; 646 my $grp = aio_group $cb;
563 647
564 aioreq_pri $pri; 648 aioreq_pri $pri;
565 add $grp aio_rename $src, $dst, sub { 649 add $grp aio_rename $src, $dst, sub {
566 if ($_[0] && $! == EXDEV) { 650 if ($_[0] && $! == EXDEV) {
567 aioreq_pri $pri; 651 aioreq_pri $pri;
568 add $grp aio_copy $src, $dst, sub { 652 add $grp aio_copy $src, $dst, sub {
569 $grp->result ($_[0]);
570
571 if (!$_[0]) {
572 aioreq_pri $pri;
573 add $grp aio_unlink $src;
574 }
575 };
576 } else {
577 $grp->result ($_[0]); 653 $grp->result ($_[0]);
654
655 if (!$_[0]) {
656 aioreq_pri $pri;
657 add $grp aio_unlink $src;
658 }
578 } 659 };
660 } else {
661 $grp->result ($_[0]);
579 }; 662 }
580
581 $grp
582 } 663 };
664
665 $grp
583} 666}
584 667
585=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 668=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
586 669
587Scans a directory (similar to C<aio_readdir>) but additionally tries to 670Scans a directory (similar to C<aio_readdir>) but additionally tries to
… …
635directory counting heuristic. 718directory counting heuristic.
636 719
637=cut 720=cut
638 721
639sub aio_scandir($$;$) { 722sub aio_scandir($$;$) {
640 aio_block {
641 my ($path, $maxreq, $cb) = @_; 723 my ($path, $maxreq, $cb) = @_;
642 724
643 my $pri = aioreq_pri; 725 my $pri = aioreq_pri;
644 726
645 my $grp = aio_group $cb; 727 my $grp = aio_group $cb;
646 728
647 $maxreq = 4 if $maxreq <= 0; 729 $maxreq = 4 if $maxreq <= 0;
648 730
649 # stat once 731 # stat once
732 aioreq_pri $pri;
733 add $grp aio_stat $path, sub {
734 return $grp->result () if $_[0];
735 my $now = time;
736 my $hash1 = join ":", (stat _)[0,1,3,7,9];
737
738 # read the directory entries
650 aioreq_pri $pri; 739 aioreq_pri $pri;
651 add $grp aio_stat $path, sub { 740 add $grp aio_readdir $path, sub {
741 my $entries = shift
652 return $grp->result () if $_[0]; 742 or return $grp->result ();
653 my $now = time;
654 my $hash1 = join ":", (stat _)[0,1,3,7,9];
655 743
656 # read the directory entries 744 # stat the dir another time
657 aioreq_pri $pri; 745 aioreq_pri $pri;
658 add $grp aio_readdir $path, sub {
659 my $entries = shift
660 or return $grp->result ();
661
662 # stat the dir another time
663 aioreq_pri $pri;
664 add $grp aio_stat $path, sub { 746 add $grp aio_stat $path, sub {
665 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 747 my $hash2 = join ":", (stat _)[0,1,3,7,9];
666 748
667 my $ndirs; 749 my $ndirs;
668 750
669 # take the slow route if anything looks fishy 751 # take the slow route if anything looks fishy
670 if ($hash1 ne $hash2 or (stat _)[9] == $now) { 752 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
671 $ndirs = -1; 753 $ndirs = -1;
672 } else { 754 } else {
673 # if nlink == 2, we are finished 755 # if nlink == 2, we are finished
674 # on non-posix-fs's, we rely on nlink < 2 756 # on non-posix-fs's, we rely on nlink < 2
675 $ndirs = (stat _)[3] - 2 757 $ndirs = (stat _)[3] - 2
676 or return $grp->result ([], $entries); 758 or return $grp->result ([], $entries);
677 } 759 }
678 760
679 # sort into likely dirs and likely nondirs 761 # sort into likely dirs and likely nondirs
680 # dirs == files without ".", short entries first 762 # dirs == files without ".", short entries first
681 $entries = [map $_->[0], 763 $entries = [map $_->[0],
682 sort { $b->[1] cmp $a->[1] } 764 sort { $b->[1] cmp $a->[1] }
683 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length], 765 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
684 @$entries]; 766 @$entries];
685 767
686 my (@dirs, @nondirs); 768 my (@dirs, @nondirs);
687 769
688 my $statgrp = add $grp aio_group sub { 770 my $statgrp = add $grp aio_group sub {
689 $grp->result (\@dirs, \@nondirs); 771 $grp->result (\@dirs, \@nondirs);
690 }; 772 };
691 773
692 limit $statgrp $maxreq; 774 limit $statgrp $maxreq;
693 feed $statgrp sub { 775 feed $statgrp sub {
694 return unless @$entries; 776 return unless @$entries;
695 my $entry = pop @$entries; 777 my $entry = pop @$entries;
696 778
697 aioreq_pri $pri; 779 aioreq_pri $pri;
698 add $statgrp aio_stat "$path/$entry/.", sub { 780 add $statgrp aio_stat "$path/$entry/.", sub {
699 if ($_[0] < 0) { 781 if ($_[0] < 0) {
700 push @nondirs, $entry; 782 push @nondirs, $entry;
701 } else { 783 } else {
702 # need to check for real directory 784 # need to check for real directory
703 aioreq_pri $pri; 785 aioreq_pri $pri;
704 add $statgrp aio_lstat "$path/$entry", sub { 786 add $statgrp aio_lstat "$path/$entry", sub {
705 if (-d _) { 787 if (-d _) {
706 push @dirs, $entry; 788 push @dirs, $entry;
707 789
708 unless (--$ndirs) { 790 unless (--$ndirs) {
709 push @nondirs, @$entries; 791 push @nondirs, @$entries;
710 feed $statgrp; 792 feed $statgrp;
711 }
712 } else {
713 push @nondirs, $entry;
714 } 793 }
794 } else {
795 push @nondirs, $entry;
715 } 796 }
716 } 797 }
717 }; 798 }
718 }; 799 };
719 }; 800 };
720 }; 801 };
721 }; 802 };
722
723 $grp
724 } 803 };
804
805 $grp
725} 806}
726 807
727=item aio_rmtree $path, $callback->($status) 808=item aio_rmtree $path, $callback->($status)
728 809
729Delete a directory tree starting (and including) C<$path>, return the 810Delete a directory tree starting (and including) C<$path>, return the
… …
733 814
734=cut 815=cut
735 816
736sub aio_rmtree; 817sub aio_rmtree;
737sub aio_rmtree($;$) { 818sub aio_rmtree($;$) {
738 aio_block {
739 my ($path, $cb) = @_; 819 my ($path, $cb) = @_;
740 820
741 my $pri = aioreq_pri; 821 my $pri = aioreq_pri;
742 my $grp = aio_group $cb; 822 my $grp = aio_group $cb;
743 823
744 aioreq_pri $pri; 824 aioreq_pri $pri;
745 add $grp aio_scandir $path, 0, sub { 825 add $grp aio_scandir $path, 0, sub {
746 my ($dirs, $nondirs) = @_; 826 my ($dirs, $nondirs) = @_;
747 827
748 my $dirgrp = aio_group sub { 828 my $dirgrp = aio_group sub {
749 add $grp aio_rmdir $path, sub { 829 add $grp aio_rmdir $path, sub {
750 $grp->result ($_[0]); 830 $grp->result ($_[0]);
751 };
752 }; 831 };
753
754 (aioreq_pri $pri), add $dirgrp aio_rmtree "$path/$_" for @$dirs;
755 (aioreq_pri $pri), add $dirgrp aio_unlink "$path/$_" for @$nondirs;
756
757 add $grp $dirgrp;
758 }; 832 };
759 833
760 $grp 834 (aioreq_pri $pri), add $dirgrp aio_rmtree "$path/$_" for @$dirs;
835 (aioreq_pri $pri), add $dirgrp aio_unlink "$path/$_" for @$nondirs;
836
837 add $grp $dirgrp;
761 } 838 };
839
840 $grp
762} 841}
842
843=item aio_sync $callback->($status)
844
845Asynchronously call sync and call the callback when finished.
763 846
764=item aio_fsync $fh, $callback->($status) 847=item aio_fsync $fh, $callback->($status)
765 848
766Asynchronously call fsync on the given filehandle and call the callback 849Asynchronously call fsync on the given filehandle and call the callback
767with the fsync result code. 850with the fsync result code.
… …
771Asynchronously call fdatasync on the given filehandle and call the 854Asynchronously call fdatasync on the given filehandle and call the
772callback with the fdatasync result code. 855callback with the fdatasync result code.
773 856
774If this call isn't available because your OS lacks it or it couldn't be 857If this call isn't available because your OS lacks it or it couldn't be
775detected, it will be emulated by calling C<fsync> instead. 858detected, it will be emulated by calling C<fsync> instead.
859
860=item aio_pathsync $path, $callback->($status)
861
862This request tries to open, fsync and close the given path. This is a
863composite request intended tosync directories after directory operations
864(E.g. rename). This might not work on all operating systems or have any
865specific effect, but usually it makes sure that directory changes get
866written to disc. It works for anything that can be opened for read-only,
867not just directories.
868
869Passes C<0> when everything went ok, and C<-1> on error.
870
871=cut
872
873sub aio_pathsync($;$) {
874 my ($path, $cb) = @_;
875
876 my $pri = aioreq_pri;
877 my $grp = aio_group $cb;
878
879 aioreq_pri $pri;
880 add $grp aio_open $path, O_RDONLY, 0, sub {
881 my ($fh) = @_;
882 if ($fh) {
883 aioreq_pri $pri;
884 add $grp aio_fsync $fh, sub {
885 $grp->result ($_[0]);
886
887 aioreq_pri $pri;
888 add $grp aio_close $fh;
889 };
890 } else {
891 $grp->result (-1);
892 }
893 };
894
895 $grp
896}
776 897
777=item aio_group $callback->(...) 898=item aio_group $callback->(...)
778 899
779This is a very special aio request: Instead of doing something, it is a 900This is a very special aio request: Instead of doing something, it is a
780container for other aio requests, which is useful if you want to bundle 901container for other aio requests, which is useful if you want to bundle
… …
917itself. Useful when you queued a lot of events but got a result early. 1038itself. Useful when you queued a lot of events but got a result early.
918 1039
919=item $grp->result (...) 1040=item $grp->result (...)
920 1041
921Set the result value(s) that will be passed to the group callback when all 1042Set the result value(s) that will be passed to the group callback when all
922subrequests have finished and set thre groups errno to the current value 1043subrequests have finished and set the groups errno to the current value
923of errno (just like calling C<errno> without an error number). By default, 1044of errno (just like calling C<errno> without an error number). By default,
924no argument will be passed and errno is zero. 1045no argument will be passed and errno is zero.
925 1046
926=item $grp->errno ([$errno]) 1047=item $grp->errno ([$errno])
927 1048
… …
996See C<poll_cb> for an example. 1117See C<poll_cb> for an example.
997 1118
998=item IO::AIO::poll_cb 1119=item IO::AIO::poll_cb
999 1120
1000Process some outstanding events on the result pipe. You have to call this 1121Process some outstanding events on the result pipe. You have to call this
1001regularly. Returns the number of events processed. Returns immediately 1122regularly. Returns C<0> if all events could be processed, or C<-1> if it
1123returned earlier for whatever reason. Returns immediately when no events
1002when no events are outstanding. The amount of events processed depends on 1124are outstanding. The amount of events processed depends on the settings of
1003the settings of C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>. 1125C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
1004 1126
1005If not all requests were processed for whatever reason, the filehandle 1127If not all requests were processed for whatever reason, the filehandle
1006will still be ready when C<poll_cb> returns. 1128will still be ready when C<poll_cb> returns, so normally you don't have to
1129do anything special to have it called later.
1007 1130
1008Example: Install an Event watcher that automatically calls 1131Example: Install an Event watcher that automatically calls
1009IO::AIO::poll_cb with high priority: 1132IO::AIO::poll_cb with high priority:
1010 1133
1011 Event->io (fd => IO::AIO::poll_fileno, 1134 Event->io (fd => IO::AIO::poll_fileno,
… …
1070Strictly equivalent to: 1193Strictly equivalent to:
1071 1194
1072 IO::AIO::poll_wait, IO::AIO::poll_cb 1195 IO::AIO::poll_wait, IO::AIO::poll_cb
1073 while IO::AIO::nreqs; 1196 while IO::AIO::nreqs;
1074 1197
1198=back
1199
1075=head3 CONTROLLING THE NUMBER OF THREADS 1200=head3 CONTROLLING THE NUMBER OF THREADS
1201
1202=over
1076 1203
1077=item IO::AIO::min_parallel $nthreads 1204=item IO::AIO::min_parallel $nthreads
1078 1205
1079Set the minimum number of AIO threads to C<$nthreads>. The current 1206Set the minimum number of AIO threads to C<$nthreads>. The current
1080default is C<8>, which means eight asynchronous operations can execute 1207default is C<8>, which means eight asynchronous operations can execute
… …
1121 1248
1122The default is probably ok in most situations, especially if thread 1249The default is probably ok in most situations, especially if thread
1123creation is fast. If thread creation is very slow on your system you might 1250creation is fast. If thread creation is very slow on your system you might
1124want to use larger values. 1251want to use larger values.
1125 1252
1126=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs 1253=item IO::AIO::max_outstanding $maxreqs
1127 1254
1128This is a very bad function to use in interactive programs because it 1255This is a very bad function to use in interactive programs because it
1129blocks, and a bad way to reduce concurrency because it is inexact: Better 1256blocks, and a bad way to reduce concurrency because it is inexact: Better
1130use an C<aio_group> together with a feed callback. 1257use an C<aio_group> together with a feed callback.
1131 1258
1132Sets the maximum number of outstanding requests to C<$nreqs>. If you 1259Sets the maximum number of outstanding requests to C<$nreqs>. If you
1133to queue up more than this number of requests, the next call to the 1260do queue up more than this number of requests, the next call to the
1134C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>) 1261C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
1135function will block until the limit is no longer exceeded. 1262function will block until the limit is no longer exceeded.
1136 1263
1137The default value is very large, so there is no practical limit on the 1264The default value is very large, so there is no practical limit on the
1138number of outstanding requests. 1265number of outstanding requests.
1139 1266
1140You can still queue as many requests as you want. Therefore, 1267You can still queue as many requests as you want. Therefore,
1141C<max_oustsanding> is mainly useful in simple scripts (with low values) or 1268C<max_outstanding> is mainly useful in simple scripts (with low values) or
1142as a stop gap to shield against fatal memory overflow (with large values). 1269as a stop gap to shield against fatal memory overflow (with large values).
1143 1270
1271=back
1272
1144=head3 STATISTICAL INFORMATION 1273=head3 STATISTICAL INFORMATION
1274
1275=over
1145 1276
1146=item IO::AIO::nreqs 1277=item IO::AIO::nreqs
1147 1278
1148Returns the number of requests currently in the ready, execute or pending 1279Returns the number of requests currently in the ready, execute or pending
1149states (i.e. for which their callback has not been invoked yet). 1280states (i.e. for which their callback has not been invoked yet).
… …
1164but not yet processed by poll_cb). 1295but not yet processed by poll_cb).
1165 1296
1166=back 1297=back
1167 1298
1168=cut 1299=cut
1169
1170# support function to convert a fd into a perl filehandle
1171sub _fd2fh {
1172 return undef if $_[0] < 0;
1173
1174 # try to generate nice filehandles
1175 my $sym = "IO::AIO::fd#$_[0]";
1176 local *$sym;
1177
1178 open *$sym, "+<&=$_[0]" # usually works under any unix
1179 or open *$sym, "<&=$_[0]" # cygwin needs this
1180 or open *$sym, ">&=$_[0]" # or this
1181 or return undef;
1182
1183 *$sym
1184}
1185 1300
1186min_parallel 8; 1301min_parallel 8;
1187 1302
1188END { flush } 1303END { flush }
1189 1304
… …
1213bytes of memory. In addition, stat requests need a stat buffer (possibly 1328bytes of memory. In addition, stat requests need a stat buffer (possibly
1214a few hundred bytes), readdir requires a result buffer and so on. Perl 1329a few hundred bytes), readdir requires a result buffer and so on. Perl
1215scalars and other data passed into aio requests will also be locked and 1330scalars and other data passed into aio requests will also be locked and
1216will consume memory till the request has entered the done state. 1331will consume memory till the request has entered the done state.
1217 1332
1218This is now awfully much, so queuing lots of requests is not usually a 1333This is not awfully much, so queuing lots of requests is not usually a
1219problem. 1334problem.
1220 1335
1221Per-thread usage: 1336Per-thread usage:
1222 1337
1223In the execution phase, some aio requests require more memory for 1338In the execution phase, some aio requests require more memory for
… …
1228 1343
1229Known bugs will be fixed in the next release. 1344Known bugs will be fixed in the next release.
1230 1345
1231=head1 SEE ALSO 1346=head1 SEE ALSO
1232 1347
1233L<Coro::AIO>. 1348L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
1349more natural syntax.
1234 1350
1235=head1 AUTHOR 1351=head1 AUTHOR
1236 1352
1237 Marc Lehmann <schmorp@schmorp.de> 1353 Marc Lehmann <schmorp@schmorp.de>
1238 http://home.schmorp.de/ 1354 http://home.schmorp.de/

Diff Legend

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