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.86 by root, Sat Oct 28 23:32:29 2006 UTC vs.
Revision 1.131 by root, Tue Jul 15 10:42:26 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.06';
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);
206 XSLoader::load ("IO::AIO", $VERSION); 217 XSLoader::load ("IO::AIO", $VERSION);
207} 218}
208 219
209=head1 FUNCTIONS 220=head1 FUNCTIONS
210 221
211=head2 AIO FUNCTIONS 222=head2 AIO REQUEST FUNCTIONS
212 223
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
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
224All requests return objects of type L<IO::AIO::REQ> that allow further 235All functions return request objects of type L<IO::AIO::REQ> that allow
225manipulation of those requests while they are in-flight. 236further manipulation of those requests while they are in-flight.
226 237
227The pathnames you pass to these routines I<must> be absolute and 238The pathnames you pass to these routines I<must> be absolute and
228encoded in byte form. The reason for the former is that at the time the 239encoded as octets. The reason for the former is that at the time the
229request is being executed, the current working directory could have 240request is being executed, the current working directory could have
230changed. Alternatively, you can make sure that you never change the 241changed. Alternatively, you can make sure that you never change the
231current working directory. 242current working directory anywhere in the program and then use relative
243paths.
232 244
233To encode pathnames to byte form, either make sure you either: a) 245To encode pathnames as octets, either make sure you either: a) always pass
234always pass in filenames you got from outside (command line, readdir 246in filenames you got from outside (command line, readdir etc.) without
235etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and encode 247tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode
236your 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
237environment, d) use Glib::filename_from_unicode on unicode filenames or e) 249environment, d) use Glib::filename_from_unicode on unicode filenames or e)
238use something else. 250use something else to ensure your scalar has the correct contents.
251
252This works, btw. independent of the internal UTF-8 bit, which IO::AIO
253handles correctly wether it is set or not.
239 254
240=over 4 255=over 4
241 256
242=item $prev_pri = aioreq_pri [$pri] 257=item $prev_pri = aioreq_pri [$pri]
243 258
263 aio_read $_[0], ..., sub { 278 aio_read $_[0], ..., sub {
264 ... 279 ...
265 }; 280 };
266 }; 281 };
267 282
283
268=item aioreq_nice $pri_adjust 284=item aioreq_nice $pri_adjust
269 285
270Similar 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
271priority, so effects are cumulative. 287priority, so the effect is cumulative.
288
272 289
273=item aio_open $pathname, $flags, $mode, $callback->($fh) 290=item aio_open $pathname, $flags, $mode, $callback->($fh)
274 291
275Asynchronously 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
276created filehandle for the file. 293created filehandle for the file.
282list. They are the same as used by C<sysopen>. 299list. They are the same as used by C<sysopen>.
283 300
284Likewise, 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
285didn'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>,
286except 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,
287and 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.
288 307
289Example: 308Example:
290 309
291 aio_open "/etc/passwd", O_RDONLY, 0, sub { 310 aio_open "/etc/passwd", O_RDONLY, 0, sub {
292 if ($_[0]) { 311 if ($_[0]) {
295 } else { 314 } else {
296 die "open failed: $!\n"; 315 die "open failed: $!\n";
297 } 316 }
298 }; 317 };
299 318
319
300=item aio_close $fh, $callback->($status) 320=item aio_close $fh, $callback->($status)
301 321
302Asynchronously close a file and call the callback with the result 322Asynchronously close a file and call the callback with the result
303code. I<WARNING:> although accepted, you should not pass in a perl 323code.
304filehandle here, as perl will likely close the file descriptor another
305time when the filehandle is destroyed. Normally, you can safely call perls
306C<close> or just let filehandles go out of scope.
307 324
308This 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
309therefore 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
310 336
311=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 337=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
312 338
313=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 339=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
314 340
315Reads 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>
316into 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
317callback 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
318like the syscall). 344like the syscall).
319 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
320The 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
321is outstanding. Modifying it can result in segfaults or WW3 (if the 356is outstanding. Modifying it can result in segfaults or World War III (if
322necessary/optional hardware is installed). 357the necessary/optional hardware is installed).
323 358
324Example: 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
325offset C<0> within the scalar: 360offset C<0> within the scalar:
326 361
327 aio_read $fh, 7, 15, $buffer, 0, sub { 362 aio_read $fh, 7, 15, $buffer, 0, sub {
328 $_[0] > 0 or die "read error: $!"; 363 $_[0] > 0 or die "read error: $!";
329 print "read $_[0] bytes: <$buffer>\n"; 364 print "read $_[0] bytes: <$buffer>\n";
330 }; 365 };
366
331 367
332=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)
333 369
334Tries 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
335reading 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
349C<$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
350bytes 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
351provides 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
352value 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
353read. 389read.
390
354 391
355=item aio_readahead $fh,$offset,$length, $callback->($retval) 392=item aio_readahead $fh,$offset,$length, $callback->($retval)
356 393
357C<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
358subsequent 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>
364file. The current file offset of the file is left unchanged. 401file. The current file offset of the file is left unchanged.
365 402
366If 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
367emulated by simply reading the data, which would have a similar effect. 404emulated by simply reading the data, which would have a similar effect.
368 405
406
369=item aio_stat $fh_or_path, $callback->($status) 407=item aio_stat $fh_or_path, $callback->($status)
370 408
371=item aio_lstat $fh, $callback->($status) 409=item aio_lstat $fh, $callback->($status)
372 410
373Works 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
386 aio_stat "/etc/passwd", sub { 424 aio_stat "/etc/passwd", sub {
387 $_[0] and die "stat failed: $!"; 425 $_[0] and die "stat failed: $!";
388 print "size is ", -s _, "\n"; 426 print "size is ", -s _, "\n";
389 }; 427 };
390 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
391=item aio_unlink $pathname, $callback->($status) 471=item aio_unlink $pathname, $callback->($status)
392 472
393Asynchronously unlink (delete) a file and call the callback with the 473Asynchronously unlink (delete) a file and call the callback with the
394result code. 474result code.
395 475
476
396=item aio_mknod $path, $mode, $dev, $callback->($status) 477=item aio_mknod $path, $mode, $dev, $callback->($status)
397 478
398[EXPERIMENTAL] 479[EXPERIMENTAL]
399 480
400Asynchronously create a device node (or fifo). See mknod(2). 481Asynchronously create a device node (or fifo). See mknod(2).
401 482
402The only (POSIX-) portable way of calling this function is: 483The only (POSIX-) portable way of calling this function is:
403 484
404 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 485 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
486
405 487
406=item aio_link $srcpath, $dstpath, $callback->($status) 488=item aio_link $srcpath, $dstpath, $callback->($status)
407 489
408Asynchronously 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
409the path C<$dstpath> and call the callback with the result code. 491the path C<$dstpath> and call the callback with the result code.
410 492
493
411=item aio_symlink $srcpath, $dstpath, $callback->($status) 494=item aio_symlink $srcpath, $dstpath, $callback->($status)
412 495
413Asynchronously 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
414the path C<$dstpath> and call the callback with the result code. 497the path C<$dstpath> and call the callback with the result code.
415 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
416=item aio_rename $srcpath, $dstpath, $callback->($status) 507=item aio_rename $srcpath, $dstpath, $callback->($status)
417 508
418Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 509Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
419rename(2) and call the callback with the result code. 510rename(2) and call the callback with the result code.
420 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
421=item aio_rmdir $pathname, $callback->($status) 520=item aio_rmdir $pathname, $callback->($status)
422 521
423Asynchronously rmdir (delete) a directory and call the callback with the 522Asynchronously rmdir (delete) a directory and call the callback with the
424result code. 523result code.
524
425 525
426=item aio_readdir $pathname, $callback->($entries) 526=item aio_readdir $pathname, $callback->($entries)
427 527
428Unlike 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
429directory (i.e. opendir + readdir + closedir). The entries will not be 529directory (i.e. opendir + readdir + closedir). The entries will not be
430sorted, and will B<NOT> include the C<.> and C<..> entries. 530sorted, and will B<NOT> include the C<.> and C<..> entries.
431 531
432The 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
433with the filenames. 533with the filenames.
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}
434 563
435=item aio_copy $srcpath, $dstpath, $callback->($status) 564=item aio_copy $srcpath, $dstpath, $callback->($status)
436 565
437Try 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
438destination) from C<$srcpath> to C<$dstpath> and call the callback with 567destination) from C<$srcpath> to C<$dstpath> and call the callback with
471 600
472 # those should not normally block. should. should. 601 # those should not normally block. should. should.
473 utime $stat[8], $stat[9], $dst; 602 utime $stat[8], $stat[9], $dst;
474 chmod $stat[2] & 07777, $dst_fh; 603 chmod $stat[2] & 07777, $dst_fh;
475 chown $stat[4], $stat[5], $dst_fh; 604 chown $stat[4], $stat[5], $dst_fh;
605
606 aioreq_pri $pri;
476 close $dst_fh; 607 add $grp aio_close $dst_fh;
477 } else { 608 } else {
478 $grp->result (-1); 609 $grp->result (-1);
479 close $src_fh; 610 close $src_fh;
480 close $dst_fh; 611 close $dst_fh;
481 612
586as 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
587directory counting heuristic. 718directory counting heuristic.
588 719
589=cut 720=cut
590 721
591sub aio_scandir($$$) { 722sub aio_scandir($$;$) {
592 my ($path, $maxreq, $cb) = @_; 723 my ($path, $maxreq, $cb) = @_;
593 724
594 my $pri = aioreq_pri; 725 my $pri = aioreq_pri;
595 726
596 my $grp = aio_group $cb; 727 my $grp = aio_group $cb;
672 }; 803 };
673 804
674 $grp 805 $grp
675} 806}
676 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
677=item aio_fsync $fh, $callback->($status) 847=item aio_fsync $fh, $callback->($status)
678 848
679Asynchronously call fsync on the given filehandle and call the callback 849Asynchronously call fsync on the given filehandle and call the callback
680with the fsync result code. 850with the fsync result code.
681 851
684Asynchronously call fdatasync on the given filehandle and call the 854Asynchronously call fdatasync on the given filehandle and call the
685callback with the fdatasync result code. 855callback with the fdatasync result code.
686 856
687If 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
688detected, 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}
689 897
690=item aio_group $callback->(...) 898=item aio_group $callback->(...)
691 899
692This 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
693container 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
830itself. 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.
831 1039
832=item $grp->result (...) 1040=item $grp->result (...)
833 1041
834Set 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
835subrequests have finished and set thre groups errno to the current value 1043subrequests have finished and set the groups errno to the current value
836of 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,
837no argument will be passed and errno is zero. 1045no argument will be passed and errno is zero.
838 1046
839=item $grp->errno ([$errno]) 1047=item $grp->errno ([$errno])
840 1048
909See C<poll_cb> for an example. 1117See C<poll_cb> for an example.
910 1118
911=item IO::AIO::poll_cb 1119=item IO::AIO::poll_cb
912 1120
913Process 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
914regularly. 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
915when no events are outstanding. The amount of events processed depends on 1124are outstanding. The amount of events processed depends on the settings of
916the 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>.
917 1126
918If not all requests were processed for whatever reason, the filehandle 1127If not all requests were processed for whatever reason, the filehandle
919will 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.
920 1130
921Example: Install an Event watcher that automatically calls 1131Example: Install an Event watcher that automatically calls
922IO::AIO::poll_cb with high priority: 1132IO::AIO::poll_cb with high priority:
923 1133
924 Event->io (fd => IO::AIO::poll_fileno, 1134 Event->io (fd => IO::AIO::poll_fileno,
933that are being processed by C<IO::AIO::poll_cb> in one call, respectively 1143that are being processed by C<IO::AIO::poll_cb> in one call, respectively
934the maximum amount of time (default C<0>, meaning infinity) spent in 1144the maximum amount of time (default C<0>, meaning infinity) spent in
935C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount 1145C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount
936of time C<poll_cb> is allowed to use). 1146of time C<poll_cb> is allowed to use).
937 1147
1148Setting C<max_poll_time> to a non-zero value creates an overhead of one
1149syscall per request processed, which is not normally a problem unless your
1150callbacks are really really fast or your OS is really really slow (I am
1151not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.
1152
938Setting these is useful if you want to ensure some level of 1153Setting these is useful if you want to ensure some level of
939interactiveness when perl is not fast enough to process all requests in 1154interactiveness when perl is not fast enough to process all requests in
940time. 1155time.
941 1156
942For interactive programs, values such as C<0.01> to C<0.1> should be fine. 1157For interactive programs, values such as C<0.01> to C<0.1> should be fine.
943 1158
944Example: Install an Event watcher that automatically calls 1159Example: Install an Event watcher that automatically calls
945IO::AIO::poll_some with low priority, to ensure that other parts of the 1160IO::AIO::poll_cb with low priority, to ensure that other parts of the
946program get the CPU sometimes even under high AIO load. 1161program get the CPU sometimes even under high AIO load.
947 1162
948 # try not to spend much more than 0.1s in poll_cb 1163 # try not to spend much more than 0.1s in poll_cb
949 IO::AIO::max_poll_time 0.1; 1164 IO::AIO::max_poll_time 0.1;
950 1165
953 poll => 'r', nice => 1, 1168 poll => 'r', nice => 1,
954 cb => &IO::AIO::poll_cb); 1169 cb => &IO::AIO::poll_cb);
955 1170
956=item IO::AIO::poll_wait 1171=item IO::AIO::poll_wait
957 1172
1173If there are any outstanding requests and none of them in the result
958Wait till the result filehandle becomes ready for reading (simply does a 1174phase, wait till the result filehandle becomes ready for reading (simply
959C<select> on the filehandle. This is useful if you want to synchronously 1175does a C<select> on the filehandle. This is useful if you want to
960wait for some requests to finish). 1176synchronously wait for some requests to finish).
961 1177
962See C<nreqs> for an example. 1178See C<nreqs> for an example.
963 1179
964=item IO::AIO::poll 1180=item IO::AIO::poll
965 1181
966Waits until some requests have been handled. 1182Waits until some requests have been handled.
967 1183
1184Returns the number of requests processed, but is otherwise strictly
968Strictly equivalent to: 1185equivalent to:
969 1186
970 IO::AIO::poll_wait, IO::AIO::poll_cb 1187 IO::AIO::poll_wait, IO::AIO::poll_cb
971 if IO::AIO::nreqs;
972 1188
973=item IO::AIO::flush 1189=item IO::AIO::flush
974 1190
975Wait till all outstanding AIO requests have been handled. 1191Wait till all outstanding AIO requests have been handled.
976 1192
977Strictly equivalent to: 1193Strictly equivalent to:
978 1194
979 IO::AIO::poll_wait, IO::AIO::poll_cb 1195 IO::AIO::poll_wait, IO::AIO::poll_cb
980 while IO::AIO::nreqs; 1196 while IO::AIO::nreqs;
981 1197
1198=back
1199
982=head3 CONTROLLING THE NUMBER OF THREADS 1200=head3 CONTROLLING THE NUMBER OF THREADS
1201
1202=over
983 1203
984=item IO::AIO::min_parallel $nthreads 1204=item IO::AIO::min_parallel $nthreads
985 1205
986Set the minimum number of AIO threads to C<$nthreads>. The current 1206Set the minimum number of AIO threads to C<$nthreads>. The current
987default is C<8>, which means eight asynchronous operations can execute 1207default is C<8>, which means eight asynchronous operations can execute
1028 1248
1029The default is probably ok in most situations, especially if thread 1249The default is probably ok in most situations, especially if thread
1030creation 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
1031want to use larger values. 1251want to use larger values.
1032 1252
1033=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs 1253=item IO::AIO::max_outstanding $maxreqs
1034 1254
1035This 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
1036blocks, 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
1037use an C<aio_group> together with a feed callback. 1257use an C<aio_group> together with a feed callback.
1038 1258
1039Sets the maximum number of outstanding requests to C<$nreqs>. If you 1259Sets the maximum number of outstanding requests to C<$nreqs>. If you
1040to 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
1041C<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>)
1042function will block until the limit is no longer exceeded. 1262function will block until the limit is no longer exceeded.
1043 1263
1044The 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
1045number of outstanding requests. 1265number of outstanding requests.
1046 1266
1047You can still queue as many requests as you want. Therefore, 1267You can still queue as many requests as you want. Therefore,
1048C<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
1049as 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).
1050 1270
1271=back
1272
1051=head3 STATISTICAL INFORMATION 1273=head3 STATISTICAL INFORMATION
1274
1275=over
1052 1276
1053=item IO::AIO::nreqs 1277=item IO::AIO::nreqs
1054 1278
1055Returns the number of requests currently in the ready, execute or pending 1279Returns the number of requests currently in the ready, execute or pending
1056states (i.e. for which their callback has not been invoked yet). 1280states (i.e. for which their callback has not been invoked yet).
1072 1296
1073=back 1297=back
1074 1298
1075=cut 1299=cut
1076 1300
1077# support function to convert a fd into a perl filehandle
1078sub _fd2fh {
1079 return undef if $_[0] < 0;
1080
1081 # try to generate nice filehandles
1082 my $sym = "IO::AIO::fd#$_[0]";
1083 local *$sym;
1084
1085 open *$sym, "+<&=$_[0]" # usually works under any unix
1086 or open *$sym, "<&=$_[0]" # cygwin needs this
1087 or open *$sym, ">&=$_[0]" # or this
1088 or return undef;
1089
1090 *$sym
1091}
1092
1093min_parallel 8; 1301min_parallel 8;
1094 1302
1095END { 1303END { flush }
1096 min_parallel 1;
1097 flush;
1098};
1099 1304
11001; 13051;
1101 1306
1102=head2 FORK BEHAVIOUR 1307=head2 FORK BEHAVIOUR
1103 1308
1123bytes of memory. In addition, stat requests need a stat buffer (possibly 1328bytes of memory. In addition, stat requests need a stat buffer (possibly
1124a 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
1125scalars 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
1126will consume memory till the request has entered the done state. 1331will consume memory till the request has entered the done state.
1127 1332
1128This 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
1129problem. 1334problem.
1130 1335
1131Per-thread usage: 1336Per-thread usage:
1132 1337
1133In the execution phase, some aio requests require more memory for 1338In the execution phase, some aio requests require more memory for
1138 1343
1139Known bugs will be fixed in the next release. 1344Known bugs will be fixed in the next release.
1140 1345
1141=head1 SEE ALSO 1346=head1 SEE ALSO
1142 1347
1143L<Coro::AIO>. 1348L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
1349more natural syntax.
1144 1350
1145=head1 AUTHOR 1351=head1 AUTHOR
1146 1352
1147 Marc Lehmann <schmorp@schmorp.de> 1353 Marc Lehmann <schmorp@schmorp.de>
1148 http://home.schmorp.de/ 1354 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines