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.87 by root, Sun Oct 29 00:52:02 2006 UTC vs.
Revision 1.136 by root, Tue Sep 30 14:07:59 2008 UTC

5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use IO::AIO; 7 use IO::AIO;
8 8
9 aio_open "/etc/passwd", O_RDONLY, 0, sub { 9 aio_open "/etc/passwd", O_RDONLY, 0, sub {
10 my ($fh) = @_; 10 my $fh = shift
11 or die "/etc/passwd: $!";
11 ... 12 ...
12 }; 13 };
13 14
14 aio_unlink "/tmp/file", sub { }; 15 aio_unlink "/tmp/file", sub { };
15 16
25 $req->cancel; # cancel request if still in queue 26 $req->cancel; # cancel request if still in queue
26 27
27 my $grp = aio_group sub { print "all stats done\n" }; 28 my $grp = aio_group sub { print "all stats done\n" };
28 add $grp aio_stat "..." for ...; 29 add $grp aio_stat "..." for ...;
29 30
31 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
32 use AnyEvent::AIO;
33
30 # AnyEvent integration 34 # EV integration
31 open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!"; 35 my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
32 my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
33 36
34 # Event integration 37 # Event integration
35 Event->io (fd => IO::AIO::poll_fileno, 38 Event->io (fd => IO::AIO::poll_fileno,
36 poll => 'r', 39 poll => 'r',
37 cb => \&IO::AIO::poll_cb); 40 cb => \&IO::AIO::poll_cb);
61etc.), 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
62normally 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
63on 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
64concurrently. 67concurrently.
65 68
66While this works on all types of file descriptors (for example sockets), 69While most of this works on all types of file descriptors (for
67using these functions on file descriptors that support nonblocking 70example sockets), using these functions on file descriptors that
68operation (again, sockets, pipes etc.) is very inefficient. Use an event 71support nonblocking operation (again, sockets, pipes etc.) is very
69loop for that (such as the L<Event|Event> module): IO::AIO will naturally 72inefficient. Use an event loop for that (such as the L<Event|Event>
70fit into such an event loop itself. 73module): IO::AIO will naturally fit into such an event loop itself.
71 74
72In this version, a number of threads are started that execute your 75In this version, a number of threads are started that execute your
73requests and signal their completion. You don't need thread support 76requests and signal their completion. You don't need thread support
74in 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
75to 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
77not 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
78files currently, for example), and they would only support aio_read and 81files currently, for example), and they would only support aio_read and
79aio_write, so the remaining functionality would have to be implemented 82aio_write, so the remaining functionality would have to be implemented
80using threads anyway. 83using threads anyway.
81 84
82Although the module will work with in the presence of other (Perl-) 85Although the module will work in the presence of other (Perl-) threads,
83threads, it is currently not reentrant in any way, so use appropriate 86it is currently not reentrant in any way, so use appropriate locking
84locking 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
85never call C<poll_cb> (or other C<aio_> functions) recursively. 88call C<poll_cb> (or other C<aio_> functions) recursively.
86 89
87=head2 EXAMPLE 90=head2 EXAMPLE
88 91
89This is a simple example that uses the Event module and loads 92This is a simple example that uses the Event module and loads
90F</etc/passwd> asynchronously: 93F</etc/passwd> asynchronously:
98 poll => 'r', 101 poll => 'r',
99 cb => \&IO::AIO::poll_cb); 102 cb => \&IO::AIO::poll_cb);
100 103
101 # queue the request to open /etc/passwd 104 # queue the request to open /etc/passwd
102 aio_open "/etc/passwd", O_RDONLY, 0, sub { 105 aio_open "/etc/passwd", O_RDONLY, 0, sub {
103 my $fh = $_[0] 106 my $fh = shift
104 or die "error while opening: $!"; 107 or die "error while opening: $!";
105 108
106 # stat'ing filehandles is generally non-blocking 109 # stat'ing filehandles is generally non-blocking
107 my $size = -s $fh; 110 my $size = -s $fh;
108 111
176Request has reached the end of its lifetime and holds no resources anymore 179Request has reached the end of its lifetime and holds no resources anymore
177(except possibly for the Perl object, but its connection to the actual 180(except possibly for the Perl object, but its connection to the actual
178aio request is severed and calling its methods will either do nothing or 181aio request is severed and calling its methods will either do nothing or
179result in a runtime error). 182result in a runtime error).
180 183
184=back
185
181=cut 186=cut
182 187
183package IO::AIO; 188package IO::AIO;
189
190use Carp ();
184 191
185no warnings; 192no warnings;
186use strict 'vars'; 193use strict 'vars';
187 194
188use base 'Exporter'; 195use base 'Exporter';
189 196
190BEGIN { 197BEGIN {
191 our $VERSION = '2.1'; 198 our $VERSION = '3.1';
192 199
193 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
194 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink 201 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir
195 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move 202 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync
196 aio_copy aio_group aio_nop aio_mknod); 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
197 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 208 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
198 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 209 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
199 min_parallel max_parallel max_idle 210 min_parallel max_parallel max_idle
200 nreqs nready npending nthreads 211 nreqs nready npending nthreads
201 max_poll_time max_poll_reqs); 212 max_poll_time max_poll_reqs);
213All the C<aio_*> calls are more or less thin wrappers around the syscall 224All the C<aio_*> calls are more or less thin wrappers around the syscall
214with the same name (sans C<aio_>). The arguments are similar or identical, 225with the same name (sans C<aio_>). The arguments are similar or identical,
215and they all accept an additional (and optional) C<$callback> argument 226and they all accept an additional (and optional) C<$callback> argument
216which must be a code reference. This code reference will get called with 227which must be a code reference. This code reference will get called with
217the syscall return code (e.g. most syscalls return C<-1> on error, unlike 228the syscall return code (e.g. most syscalls return C<-1> on error, unlike
218perl, which usually delivers "false") as it's sole argument when the given 229perl, which usually delivers "false") as its sole argument after the given
219syscall has been executed asynchronously. 230syscall has been executed asynchronously.
220 231
221All functions expecting a filehandle keep a copy of the filehandle 232All functions expecting a filehandle keep a copy of the filehandle
222internally until the request has finished. 233internally until the request has finished.
223 234
237your pathnames to the locale (or other) encoding in effect in the user 248your pathnames to the locale (or other) encoding in effect in the user
238environment, d) use Glib::filename_from_unicode on unicode filenames or e) 249environment, d) use Glib::filename_from_unicode on unicode filenames or e)
239use something else to ensure your scalar has the correct contents. 250use something else to ensure your scalar has the correct contents.
240 251
241This works, btw. independent of the internal UTF-8 bit, which IO::AIO 252This works, btw. independent of the internal UTF-8 bit, which IO::AIO
242handles correctly wether it is set or not. 253handles correctly whether it is set or not.
243 254
244=over 4 255=over 4
245 256
246=item $prev_pri = aioreq_pri [$pri] 257=item $prev_pri = aioreq_pri [$pri]
247 258
267 aio_read $_[0], ..., sub { 278 aio_read $_[0], ..., sub {
268 ... 279 ...
269 }; 280 };
270 }; 281 };
271 282
283
272=item aioreq_nice $pri_adjust 284=item aioreq_nice $pri_adjust
273 285
274Similar 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
275priority, so the effect is cumulative. 287priority, so the effect is cumulative.
288
276 289
277=item aio_open $pathname, $flags, $mode, $callback->($fh) 290=item aio_open $pathname, $flags, $mode, $callback->($fh)
278 291
279Asynchronously 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
280created filehandle for the file. 293created filehandle for the file.
286list. They are the same as used by C<sysopen>. 299list. They are the same as used by C<sysopen>.
287 300
288Likewise, 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
289didn'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>,
290except 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,
291and 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.
292 307
293Example: 308Example:
294 309
295 aio_open "/etc/passwd", O_RDONLY, 0, sub { 310 aio_open "/etc/passwd", O_RDONLY, 0, sub {
296 if ($_[0]) { 311 if ($_[0]) {
299 } else { 314 } else {
300 die "open failed: $!\n"; 315 die "open failed: $!\n";
301 } 316 }
302 }; 317 };
303 318
319
304=item aio_close $fh, $callback->($status) 320=item aio_close $fh, $callback->($status)
305 321
306Asynchronously close a file and call the callback with the result 322Asynchronously close a file and call the callback with the result
307code. I<WARNING:> although accepted, you should not pass in a perl 323code.
308filehandle here, as perl will likely close the file descriptor another
309time when the filehandle is destroyed. Normally, you can safely call perls
310C<close> or just let filehandles go out of scope.
311 324
312This 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
313therefore 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
314 336
315=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 337=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
316 338
317=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 339=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
318 340
319Reads 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>
320into 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
321callback 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
322like the syscall). 344like the syscall).
323 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
324The 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
325is outstanding. Modifying it can result in segfaults or WW3 (if the 356is outstanding. Modifying it can result in segfaults or World War III (if
326necessary/optional hardware is installed). 357the necessary/optional hardware is installed).
327 358
328Example: 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
329offset C<0> within the scalar: 360offset C<0> within the scalar:
330 361
331 aio_read $fh, 7, 15, $buffer, 0, sub { 362 aio_read $fh, 7, 15, $buffer, 0, sub {
332 $_[0] > 0 or die "read error: $!"; 363 $_[0] > 0 or die "read error: $!";
333 print "read $_[0] bytes: <$buffer>\n"; 364 print "read $_[0] bytes: <$buffer>\n";
334 }; 365 };
366
335 367
336=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)
337 369
338Tries 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
339reading 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
353C<$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
354bytes 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
355provides 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
356value 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
357read. 389read.
390
358 391
359=item aio_readahead $fh,$offset,$length, $callback->($retval) 392=item aio_readahead $fh,$offset,$length, $callback->($retval)
360 393
361C<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
362subsequent 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>
368file. The current file offset of the file is left unchanged. 401file. The current file offset of the file is left unchanged.
369 402
370If 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
371emulated by simply reading the data, which would have a similar effect. 404emulated by simply reading the data, which would have a similar effect.
372 405
406
373=item aio_stat $fh_or_path, $callback->($status) 407=item aio_stat $fh_or_path, $callback->($status)
374 408
375=item aio_lstat $fh, $callback->($status) 409=item aio_lstat $fh, $callback->($status)
376 410
377Works 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
390 aio_stat "/etc/passwd", sub { 424 aio_stat "/etc/passwd", sub {
391 $_[0] and die "stat failed: $!"; 425 $_[0] and die "stat failed: $!";
392 print "size is ", -s _, "\n"; 426 print "size is ", -s _, "\n";
393 }; 427 };
394 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
395=item aio_unlink $pathname, $callback->($status) 471=item aio_unlink $pathname, $callback->($status)
396 472
397Asynchronously unlink (delete) a file and call the callback with the 473Asynchronously unlink (delete) a file and call the callback with the
398result code. 474result code.
399 475
476
400=item aio_mknod $path, $mode, $dev, $callback->($status) 477=item aio_mknod $path, $mode, $dev, $callback->($status)
401 478
402[EXPERIMENTAL] 479[EXPERIMENTAL]
403 480
404Asynchronously create a device node (or fifo). See mknod(2). 481Asynchronously create a device node (or fifo). See mknod(2).
405 482
406The only (POSIX-) portable way of calling this function is: 483The only (POSIX-) portable way of calling this function is:
407 484
408 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 485 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
486
409 487
410=item aio_link $srcpath, $dstpath, $callback->($status) 488=item aio_link $srcpath, $dstpath, $callback->($status)
411 489
412Asynchronously 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
413the path C<$dstpath> and call the callback with the result code. 491the path C<$dstpath> and call the callback with the result code.
414 492
493
415=item aio_symlink $srcpath, $dstpath, $callback->($status) 494=item aio_symlink $srcpath, $dstpath, $callback->($status)
416 495
417Asynchronously 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
418the path C<$dstpath> and call the callback with the result code. 497the path C<$dstpath> and call the callback with the result code.
419 498
499
500=item aio_readlink $path, $callback->($link)
501
502Asynchronously read the symlink specified by C<$path> and pass it to
503the callback. If an error occurs, nothing or undef gets passed to the
504callback.
505
506
420=item aio_rename $srcpath, $dstpath, $callback->($status) 507=item aio_rename $srcpath, $dstpath, $callback->($status)
421 508
422Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 509Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
423rename(2) and call the callback with the result code. 510rename(2) and call the callback with the result code.
424 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
425=item aio_rmdir $pathname, $callback->($status) 520=item aio_rmdir $pathname, $callback->($status)
426 521
427Asynchronously rmdir (delete) a directory and call the callback with the 522Asynchronously rmdir (delete) a directory and call the callback with the
428result code. 523result code.
524
429 525
430=item aio_readdir $pathname, $callback->($entries) 526=item aio_readdir $pathname, $callback->($entries)
431 527
432Unlike 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
433directory (i.e. opendir + readdir + closedir). The entries will not be 529directory (i.e. opendir + readdir + closedir). The entries will not be
434sorted, and will B<NOT> include the C<.> and C<..> entries. 530sorted, and will B<NOT> include the C<.> and C<..> entries.
435 531
436The 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
437with the filenames. 533with the filenames.
438 534
535
536=item aio_load $path, $data, $callback->($status)
537
538This is a composite request that tries to fully load the given file into
539memory. Status is the same as with aio_read.
540
541=cut
542
543sub aio_load($$;$) {
544 my ($path, undef, $cb) = @_;
545 my $data = \$_[1];
546
547 my $pri = aioreq_pri;
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);
554
555 aioreq_pri $pri;
556 add $grp aio_read $fh, 0, (-s $fh), $$data, 0, sub {
557 $grp->result ($_[0]);
558 };
559 };
560
561 $grp
562}
563
439=item aio_copy $srcpath, $dstpath, $callback->($status) 564=item aio_copy $srcpath, $dstpath, $callback->($status)
440 565
441Try 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
442destination) from C<$srcpath> to C<$dstpath> and call the callback with 567destination) from C<$srcpath> to C<$dstpath> and call the callback with
443the C<0> (error) or C<-1> ok. 568the C<0> (error) or C<-1> ok.
444 569
445This is a composite request that it creates the destination file with 570This is a composite request that creates the destination file with
446mode 0200 and copies the contents of the source file into it using 571mode 0200 and copies the contents of the source file into it using
447C<aio_sendfile>, followed by restoring atime, mtime, access mode and 572C<aio_sendfile>, followed by restoring atime, mtime, access mode and
448uid/gid, in that order. 573uid/gid, in that order.
449 574
450If an error occurs, the partial destination file will be unlinked, if 575If an error occurs, the partial destination file will be unlinked, if
475 600
476 # those should not normally block. should. should. 601 # those should not normally block. should. should.
477 utime $stat[8], $stat[9], $dst; 602 utime $stat[8], $stat[9], $dst;
478 chmod $stat[2] & 07777, $dst_fh; 603 chmod $stat[2] & 07777, $dst_fh;
479 chown $stat[4], $stat[5], $dst_fh; 604 chown $stat[4], $stat[5], $dst_fh;
605
606 aioreq_pri $pri;
480 close $dst_fh; 607 add $grp aio_close $dst_fh;
481 } else { 608 } else {
482 $grp->result (-1); 609 $grp->result (-1);
483 close $src_fh; 610 close $src_fh;
484 close $dst_fh; 611 close $dst_fh;
485 612
590as those tend to return 0 or 1 as link counts, which disables the 717as those tend to return 0 or 1 as link counts, which disables the
591directory counting heuristic. 718directory counting heuristic.
592 719
593=cut 720=cut
594 721
595sub aio_scandir($$$) { 722sub aio_scandir($$;$) {
596 my ($path, $maxreq, $cb) = @_; 723 my ($path, $maxreq, $cb) = @_;
597 724
598 my $pri = aioreq_pri; 725 my $pri = aioreq_pri;
599 726
600 my $grp = aio_group $cb; 727 my $grp = aio_group $cb;
676 }; 803 };
677 804
678 $grp 805 $grp
679} 806}
680 807
808=item aio_rmtree $path, $callback->($status)
809
810Delete a directory tree starting (and including) C<$path>, return the
811status of the final C<rmdir> only. This is a composite request that
812uses C<aio_scandir> to recurse into and rmdir directories, and unlink
813everything else.
814
815=cut
816
817sub aio_rmtree;
818sub aio_rmtree($;$) {
819 my ($path, $cb) = @_;
820
821 my $pri = aioreq_pri;
822 my $grp = aio_group $cb;
823
824 aioreq_pri $pri;
825 add $grp aio_scandir $path, 0, sub {
826 my ($dirs, $nondirs) = @_;
827
828 my $dirgrp = aio_group sub {
829 add $grp aio_rmdir $path, sub {
830 $grp->result ($_[0]);
831 };
832 };
833
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;
838 };
839
840 $grp
841}
842
843=item aio_sync $callback->($status)
844
845Asynchronously call sync and call the callback when finished.
846
681=item aio_fsync $fh, $callback->($status) 847=item aio_fsync $fh, $callback->($status)
682 848
683Asynchronously call fsync on the given filehandle and call the callback 849Asynchronously call fsync on the given filehandle and call the callback
684with the fsync result code. 850with the fsync result code.
685 851
688Asynchronously call fdatasync on the given filehandle and call the 854Asynchronously call fdatasync on the given filehandle and call the
689callback with the fdatasync result code. 855callback with the fdatasync result code.
690 856
691If 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
692detected, 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 to sync 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}
693 897
694=item aio_group $callback->(...) 898=item aio_group $callback->(...)
695 899
696This 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
697container 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
809Their lifetime, simplified, looks like this: when they are empty, they 1013Their lifetime, simplified, looks like this: when they are empty, they
810will finish very quickly. If they contain only requests that are in the 1014will finish very quickly. If they contain only requests that are in the
811C<done> state, they will also finish. Otherwise they will continue to 1015C<done> state, they will also finish. Otherwise they will continue to
812exist. 1016exist.
813 1017
814That means after creating a group you have some time to add requests. And 1018That means after creating a group you have some time to add requests
815in the callbacks of those requests, you can add further requests to the 1019(precisely before the callback has been invoked, which is only done within
816group. And only when all those requests have finished will the the group 1020the C<poll_cb>). And in the callbacks of those requests, you can add
817itself finish. 1021further requests to the group. And only when all those requests have
1022finished will the the group itself finish.
818 1023
819=over 4 1024=over 4
820 1025
821=item add $grp ... 1026=item add $grp ...
822 1027
834itself. Useful when you queued a lot of events but got a result early. 1039itself. Useful when you queued a lot of events but got a result early.
835 1040
836=item $grp->result (...) 1041=item $grp->result (...)
837 1042
838Set the result value(s) that will be passed to the group callback when all 1043Set the result value(s) that will be passed to the group callback when all
839subrequests have finished and set thre groups errno to the current value 1044subrequests have finished and set the groups errno to the current value
840of errno (just like calling C<errno> without an error number). By default, 1045of errno (just like calling C<errno> without an error number). By default,
841no argument will be passed and errno is zero. 1046no argument will be passed and errno is zero.
842 1047
843=item $grp->errno ([$errno]) 1048=item $grp->errno ([$errno])
844 1049
913See C<poll_cb> for an example. 1118See C<poll_cb> for an example.
914 1119
915=item IO::AIO::poll_cb 1120=item IO::AIO::poll_cb
916 1121
917Process some outstanding events on the result pipe. You have to call this 1122Process some outstanding events on the result pipe. You have to call this
918regularly. Returns the number of events processed. Returns immediately 1123regularly. Returns C<0> if all events could be processed, or C<-1> if it
1124returned earlier for whatever reason. Returns immediately when no events
919when no events are outstanding. The amount of events processed depends on 1125are outstanding. The amount of events processed depends on the settings of
920the settings of C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>. 1126C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
921 1127
922If not all requests were processed for whatever reason, the filehandle 1128If not all requests were processed for whatever reason, the filehandle
923will still be ready when C<poll_cb> returns. 1129will still be ready when C<poll_cb> returns, so normally you don't have to
1130do anything special to have it called later.
924 1131
925Example: Install an Event watcher that automatically calls 1132Example: Install an Event watcher that automatically calls
926IO::AIO::poll_cb with high priority: 1133IO::AIO::poll_cb with high priority:
927 1134
928 Event->io (fd => IO::AIO::poll_fileno, 1135 Event->io (fd => IO::AIO::poll_fileno,
937that are being processed by C<IO::AIO::poll_cb> in one call, respectively 1144that are being processed by C<IO::AIO::poll_cb> in one call, respectively
938the maximum amount of time (default C<0>, meaning infinity) spent in 1145the maximum amount of time (default C<0>, meaning infinity) spent in
939C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount 1146C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount
940of time C<poll_cb> is allowed to use). 1147of time C<poll_cb> is allowed to use).
941 1148
1149Setting C<max_poll_time> to a non-zero value creates an overhead of one
1150syscall per request processed, which is not normally a problem unless your
1151callbacks are really really fast or your OS is really really slow (I am
1152not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.
1153
942Setting these is useful if you want to ensure some level of 1154Setting these is useful if you want to ensure some level of
943interactiveness when perl is not fast enough to process all requests in 1155interactiveness when perl is not fast enough to process all requests in
944time. 1156time.
945 1157
946For interactive programs, values such as C<0.01> to C<0.1> should be fine. 1158For interactive programs, values such as C<0.01> to C<0.1> should be fine.
947 1159
948Example: Install an Event watcher that automatically calls 1160Example: Install an Event watcher that automatically calls
949IO::AIO::poll_some with low priority, to ensure that other parts of the 1161IO::AIO::poll_cb with low priority, to ensure that other parts of the
950program get the CPU sometimes even under high AIO load. 1162program get the CPU sometimes even under high AIO load.
951 1163
952 # try not to spend much more than 0.1s in poll_cb 1164 # try not to spend much more than 0.1s in poll_cb
953 IO::AIO::max_poll_time 0.1; 1165 IO::AIO::max_poll_time 0.1;
954 1166
957 poll => 'r', nice => 1, 1169 poll => 'r', nice => 1,
958 cb => &IO::AIO::poll_cb); 1170 cb => &IO::AIO::poll_cb);
959 1171
960=item IO::AIO::poll_wait 1172=item IO::AIO::poll_wait
961 1173
1174If there are any outstanding requests and none of them in the result
962Wait till the result filehandle becomes ready for reading (simply does a 1175phase, wait till the result filehandle becomes ready for reading (simply
963C<select> on the filehandle. This is useful if you want to synchronously 1176does a C<select> on the filehandle. This is useful if you want to
964wait for some requests to finish). 1177synchronously wait for some requests to finish).
965 1178
966See C<nreqs> for an example. 1179See C<nreqs> for an example.
967 1180
968=item IO::AIO::poll 1181=item IO::AIO::poll
969 1182
970Waits until some requests have been handled. 1183Waits until some requests have been handled.
971 1184
1185Returns the number of requests processed, but is otherwise strictly
972Strictly equivalent to: 1186equivalent to:
973 1187
974 IO::AIO::poll_wait, IO::AIO::poll_cb 1188 IO::AIO::poll_wait, IO::AIO::poll_cb
975 if IO::AIO::nreqs;
976 1189
977=item IO::AIO::flush 1190=item IO::AIO::flush
978 1191
979Wait till all outstanding AIO requests have been handled. 1192Wait till all outstanding AIO requests have been handled.
980 1193
981Strictly equivalent to: 1194Strictly equivalent to:
982 1195
983 IO::AIO::poll_wait, IO::AIO::poll_cb 1196 IO::AIO::poll_wait, IO::AIO::poll_cb
984 while IO::AIO::nreqs; 1197 while IO::AIO::nreqs;
985 1198
1199=back
1200
986=head3 CONTROLLING THE NUMBER OF THREADS 1201=head3 CONTROLLING THE NUMBER OF THREADS
1202
1203=over
987 1204
988=item IO::AIO::min_parallel $nthreads 1205=item IO::AIO::min_parallel $nthreads
989 1206
990Set the minimum number of AIO threads to C<$nthreads>. The current 1207Set the minimum number of AIO threads to C<$nthreads>. The current
991default is C<8>, which means eight asynchronous operations can execute 1208default is C<8>, which means eight asynchronous operations can execute
1032 1249
1033The default is probably ok in most situations, especially if thread 1250The default is probably ok in most situations, especially if thread
1034creation is fast. If thread creation is very slow on your system you might 1251creation is fast. If thread creation is very slow on your system you might
1035want to use larger values. 1252want to use larger values.
1036 1253
1037=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs 1254=item IO::AIO::max_outstanding $maxreqs
1038 1255
1039This is a very bad function to use in interactive programs because it 1256This is a very bad function to use in interactive programs because it
1040blocks, and a bad way to reduce concurrency because it is inexact: Better 1257blocks, and a bad way to reduce concurrency because it is inexact: Better
1041use an C<aio_group> together with a feed callback. 1258use an C<aio_group> together with a feed callback.
1042 1259
1043Sets the maximum number of outstanding requests to C<$nreqs>. If you 1260Sets the maximum number of outstanding requests to C<$nreqs>. If you
1044to queue up more than this number of requests, the next call to the 1261do queue up more than this number of requests, the next call to the
1045C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>) 1262C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
1046function will block until the limit is no longer exceeded. 1263function will block until the limit is no longer exceeded.
1047 1264
1048The default value is very large, so there is no practical limit on the 1265The default value is very large, so there is no practical limit on the
1049number of outstanding requests. 1266number of outstanding requests.
1050 1267
1051You can still queue as many requests as you want. Therefore, 1268You can still queue as many requests as you want. Therefore,
1052C<max_oustsanding> is mainly useful in simple scripts (with low values) or 1269C<max_outstanding> is mainly useful in simple scripts (with low values) or
1053as a stop gap to shield against fatal memory overflow (with large values). 1270as a stop gap to shield against fatal memory overflow (with large values).
1054 1271
1272=back
1273
1055=head3 STATISTICAL INFORMATION 1274=head3 STATISTICAL INFORMATION
1275
1276=over
1056 1277
1057=item IO::AIO::nreqs 1278=item IO::AIO::nreqs
1058 1279
1059Returns the number of requests currently in the ready, execute or pending 1280Returns the number of requests currently in the ready, execute or pending
1060states (i.e. for which their callback has not been invoked yet). 1281states (i.e. for which their callback has not been invoked yet).
1076 1297
1077=back 1298=back
1078 1299
1079=cut 1300=cut
1080 1301
1081# support function to convert a fd into a perl filehandle
1082sub _fd2fh {
1083 return undef if $_[0] < 0;
1084
1085 # try to generate nice filehandles
1086 my $sym = "IO::AIO::fd#$_[0]";
1087 local *$sym;
1088
1089 open *$sym, "+<&=$_[0]" # usually works under any unix
1090 or open *$sym, "<&=$_[0]" # cygwin needs this
1091 or open *$sym, ">&=$_[0]" # or this
1092 or return undef;
1093
1094 *$sym
1095}
1096
1097min_parallel 8; 1302min_parallel 8;
1098 1303
1099END { 1304END { flush }
1100 min_parallel 1;
1101 flush;
1102};
1103 1305
11041; 13061;
1105 1307
1106=head2 FORK BEHAVIOUR 1308=head2 FORK BEHAVIOUR
1107 1309
1127bytes of memory. In addition, stat requests need a stat buffer (possibly 1329bytes of memory. In addition, stat requests need a stat buffer (possibly
1128a few hundred bytes), readdir requires a result buffer and so on. Perl 1330a few hundred bytes), readdir requires a result buffer and so on. Perl
1129scalars and other data passed into aio requests will also be locked and 1331scalars and other data passed into aio requests will also be locked and
1130will consume memory till the request has entered the done state. 1332will consume memory till the request has entered the done state.
1131 1333
1132This is now awfully much, so queuing lots of requests is not usually a 1334This is not awfully much, so queuing lots of requests is not usually a
1133problem. 1335problem.
1134 1336
1135Per-thread usage: 1337Per-thread usage:
1136 1338
1137In the execution phase, some aio requests require more memory for 1339In the execution phase, some aio requests require more memory for
1142 1344
1143Known bugs will be fixed in the next release. 1345Known bugs will be fixed in the next release.
1144 1346
1145=head1 SEE ALSO 1347=head1 SEE ALSO
1146 1348
1147L<Coro::AIO>. 1349L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
1350more natural syntax.
1148 1351
1149=head1 AUTHOR 1352=head1 AUTHOR
1150 1353
1151 Marc Lehmann <schmorp@schmorp.de> 1354 Marc Lehmann <schmorp@schmorp.de>
1152 http://home.schmorp.de/ 1355 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines