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.181 by root, Tue May 4 21:14:01 2010 UTC vs.
Revision 1.215 by root, Tue Oct 4 18:22:37 2011 UTC

… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '3.65'; 173 our $VERSION = '4.0';
174 174
175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close 175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync 177 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead 178 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_fallocate
179 aio_pathsync aio_readahead
179 aio_rename aio_link aio_move aio_copy aio_group 180 aio_rename aio_link aio_move aio_copy aio_group
180 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown 181 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
181 aio_chmod aio_utime aio_truncate 182 aio_chmod aio_utime aio_truncate
182 aio_msync aio_mtouch aio_statvfs); 183 aio_msync aio_mtouch aio_mlock aio_mlockall
184 aio_statvfs
185 aio_wd);
183 186
184 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 187 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
185 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 188 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
186 min_parallel max_parallel max_idle 189 min_parallel max_parallel max_idle idle_timeout
187 nreqs nready npending nthreads 190 nreqs nready npending nthreads
188 max_poll_time max_poll_reqs 191 max_poll_time max_poll_reqs
189 sendfile fadvise); 192 sendfile fadvise madvise
193 mmap munmap munlock munlockall);
190 194
191 push @AIO_REQ, qw(aio_busy); # not exported 195 push @AIO_REQ, qw(aio_busy); # not exported
192 196
193 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 197 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
194 198
… …
202 206
203This section simply lists the prototypes of the most important functions 207This section simply lists the prototypes of the most important functions
204for quick reference. See the following sections for function-by-function 208for quick reference. See the following sections for function-by-function
205documentation. 209documentation.
206 210
211 aio_wd $pathname, $callback->($wd)
207 aio_open $pathname, $flags, $mode, $callback->($fh) 212 aio_open $pathname, $flags, $mode, $callback->($fh)
208 aio_close $fh, $callback->($status) 213 aio_close $fh, $callback->($status)
209 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 214 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
210 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 215 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
211 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 216 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
… …
216 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 221 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
217 aio_chown $fh_or_path, $uid, $gid, $callback->($status) 222 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
218 aio_truncate $fh_or_path, $offset, $callback->($status) 223 aio_truncate $fh_or_path, $offset, $callback->($status)
219 aio_chmod $fh_or_path, $mode, $callback->($status) 224 aio_chmod $fh_or_path, $mode, $callback->($status)
220 aio_unlink $pathname, $callback->($status) 225 aio_unlink $pathname, $callback->($status)
221 aio_mknod $path, $mode, $dev, $callback->($status) 226 aio_mknod $pathname, $mode, $dev, $callback->($status)
222 aio_link $srcpath, $dstpath, $callback->($status) 227 aio_link $srcpath, $dstpath, $callback->($status)
223 aio_symlink $srcpath, $dstpath, $callback->($status) 228 aio_symlink $srcpath, $dstpath, $callback->($status)
224 aio_readlink $path, $callback->($link) 229 aio_readlink $pathname, $callback->($link)
230 aio_realpath $pathname, $callback->($link)
225 aio_rename $srcpath, $dstpath, $callback->($status) 231 aio_rename $srcpath, $dstpath, $callback->($status)
226 aio_mkdir $pathname, $mode, $callback->($status) 232 aio_mkdir $pathname, $mode, $callback->($status)
227 aio_rmdir $pathname, $callback->($status) 233 aio_rmdir $pathname, $callback->($status)
228 aio_readdir $pathname, $callback->($entries) 234 aio_readdir $pathname, $callback->($entries)
229 aio_readdirx $pathname, $flags, $callback->($entries, $flags) 235 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
230 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST 236 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
231 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN 237 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
238 aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
232 aio_load $path, $data, $callback->($status) 239 aio_load $pathname, $data, $callback->($status)
233 aio_copy $srcpath, $dstpath, $callback->($status) 240 aio_copy $srcpath, $dstpath, $callback->($status)
234 aio_move $srcpath, $dstpath, $callback->($status) 241 aio_move $srcpath, $dstpath, $callback->($status)
235 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
236 aio_rmtree $path, $callback->($status) 242 aio_rmtree $pathname, $callback->($status)
237 aio_sync $callback->($status) 243 aio_sync $callback->($status)
244 aio_syncfs $fh, $callback->($status)
238 aio_fsync $fh, $callback->($status) 245 aio_fsync $fh, $callback->($status)
239 aio_fdatasync $fh, $callback->($status) 246 aio_fdatasync $fh, $callback->($status)
240 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 247 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
241 aio_pathsync $path, $callback->($status) 248 aio_pathsync $pathname, $callback->($status)
242 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 249 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
243 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 250 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
251 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
252 aio_mlockall $flags, $callback->($status)
244 aio_group $callback->(...) 253 aio_group $callback->(...)
245 aio_nop $callback->() 254 aio_nop $callback->()
246 255
247 $prev_pri = aioreq_pri [$pri] 256 $prev_pri = aioreq_pri [$pri]
248 aioreq_nice $pri_adjust 257 aioreq_nice $pri_adjust
… …
254 IO::AIO::max_poll_reqs $nreqs 263 IO::AIO::max_poll_reqs $nreqs
255 IO::AIO::max_poll_time $seconds 264 IO::AIO::max_poll_time $seconds
256 IO::AIO::min_parallel $nthreads 265 IO::AIO::min_parallel $nthreads
257 IO::AIO::max_parallel $nthreads 266 IO::AIO::max_parallel $nthreads
258 IO::AIO::max_idle $nthreads 267 IO::AIO::max_idle $nthreads
268 IO::AIO::idle_timeout $seconds
259 IO::AIO::max_outstanding $maxreqs 269 IO::AIO::max_outstanding $maxreqs
260 IO::AIO::nreqs 270 IO::AIO::nreqs
261 IO::AIO::nready 271 IO::AIO::nready
262 IO::AIO::npending 272 IO::AIO::npending
263 273
264 IO::AIO::sendfile $ofh, $ifh, $offset, $count 274 IO::AIO::sendfile $ofh, $ifh, $offset, $count
265 IO::AIO::fadvise $fh, $offset, $len, $advice 275 IO::AIO::fadvise $fh, $offset, $len, $advice
266 IO::AIO::mlockall $flags 276 IO::AIO::madvise $scalar, $offset, $length, $advice
277 IO::AIO::mprotect $scalar, $offset, $length, $protect
278 IO::AIO::munlock $scalar, $offset = 0, $length = undef
267 IO::AIO::munlockall 279 IO::AIO::munlockall
268 280
269=head2 AIO REQUEST FUNCTIONS 281=head2 AIO REQUEST FUNCTIONS
270 282
271All the C<aio_*> calls are more or less thin wrappers around the syscall 283All the C<aio_*> calls are more or less thin wrappers around the syscall
272with the same name (sans C<aio_>). The arguments are similar or identical, 284with the same name (sans C<aio_>). The arguments are similar or identical,
273and they all accept an additional (and optional) C<$callback> argument 285and they all accept an additional (and optional) C<$callback> argument
274which must be a code reference. This code reference will get called with 286which must be a code reference. This code reference will be called after
275the syscall return code (e.g. most syscalls return C<-1> on error, unlike 287the syscall has been executed in an asynchronous fashion. The results
276perl, which usually delivers "false") as its sole argument after the given 288of the request will be passed as arguments to the callback (and, if an
277syscall has been executed asynchronously. 289error occured, in C<$!>) - for most requests the syscall return code (e.g.
290most syscalls return C<-1> on error, unlike perl, which usually delivers
291"false").
292
293Some requests (such as C<aio_readdir>) pass the actual results and
294communicate failures by passing C<undef>.
278 295
279All functions expecting a filehandle keep a copy of the filehandle 296All functions expecting a filehandle keep a copy of the filehandle
280internally until the request has finished. 297internally until the request has finished.
281 298
282All functions return request objects of type L<IO::AIO::REQ> that allow 299All functions return request objects of type L<IO::AIO::REQ> that allow
283further manipulation of those requests while they are in-flight. 300further manipulation of those requests while they are in-flight.
284 301
285The pathnames you pass to these routines I<must> be absolute and 302The pathnames you pass to these routines I<should> be absolute. The
286encoded as octets. The reason for the former is that at the time the 303reason for this is that at the time the request is being executed, the
287request is being executed, the current working directory could have 304current working directory could have changed. Alternatively, you can
288changed. Alternatively, you can make sure that you never change the 305make sure that you never change the current working directory anywhere
289current working directory anywhere in the program and then use relative 306in the program and then use relative paths. You can also take advantage
290paths. 307of IO::AIOs working directory abstraction, that lets you specify paths
308relative to some previously-opened "working directory object" - see the
309description of the C<IO::AIO::WD> class later in this document.
291 310
292To encode pathnames as octets, either make sure you either: a) always pass 311To encode pathnames as octets, either make sure you either: a) always pass
293in filenames you got from outside (command line, readdir etc.) without 312in filenames you got from outside (command line, readdir etc.) without
294tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode 313tinkering, b) are in your native filesystem encoding, c) use the Encode
295your pathnames to the locale (or other) encoding in effect in the user 314module and encode your pathnames to the locale (or other) encoding in
296environment, d) use Glib::filename_from_unicode on unicode filenames or e) 315effect in the user environment, d) use Glib::filename_from_unicode on
297use something else to ensure your scalar has the correct contents. 316unicode filenames or e) use something else to ensure your scalar has the
317correct contents.
298 318
299This works, btw. independent of the internal UTF-8 bit, which IO::AIO 319This works, btw. independent of the internal UTF-8 bit, which IO::AIO
300handles correctly whether it is set or not. 320handles correctly whether it is set or not.
301 321
302=over 4 322=over 4
… …
361 } else { 381 } else {
362 die "open failed: $!\n"; 382 die "open failed: $!\n";
363 } 383 }
364 }; 384 };
365 385
386In addition to all the common open modes/flags (C<O_RDONLY>, C<O_WRONLY>,
387C<O_RDWR>, C<O_CREAT>, C<O_TRUNC>, C<O_EXCL> and C<O_APPEND>), the
388following POSIX and non-POSIX constants are available (missing ones on
389your system are, as usual, C<0>):
390
391C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
392C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
393C<O_RSYNC>, C<O_SYNC> and C<O_TTY_INIT>.
394
366 395
367=item aio_close $fh, $callback->($status) 396=item aio_close $fh, $callback->($status)
368 397
369Asynchronously close a file and call the callback with the result 398Asynchronously close a file and call the callback with the result
370code. 399code.
… …
420 449
421Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts 450Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
422reading at byte offset C<$in_offset>, and starts writing at the current 451reading at byte offset C<$in_offset>, and starts writing at the current
423file offset of C<$out_fh>. Because of that, it is not safe to issue more 452file offset of C<$out_fh>. Because of that, it is not safe to issue more
424than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each 453than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
425other. 454other. The same C<$in_fh> works fine though, as this function does not
455move or use the file offset of C<$in_fh>.
426 456
457Please note that C<aio_sendfile> can read more bytes from C<$in_fh> than
458are written, and there is no way to find out how many more bytes have been
459read from C<aio_sendfile> alone, as C<aio_sendfile> only provides the
460number of bytes written to C<$out_fh>. Only if the result value equals
461C<$length> one can assume that C<$length> bytes have been read.
462
463Unlike with other C<aio_> functions, it makes a lot of sense to use
464C<aio_sendfile> on non-blocking sockets, as long as one end (typically
465the C<$in_fh>) is a file - the file I/O will then be asynchronous, while
466the socket I/O will be non-blocking. Note, however, that you can run
467into a trap where C<aio_sendfile> reads some data with readahead, then
468fails to write all data, and when the socket is ready the next time, the
469data in the cache is already lost, forcing C<aio_sendfile> to again hit
470the disk. Explicit C<aio_read> + C<aio_write> let's you better control
471resource usage.
472
427This call tries to make use of a native C<sendfile> syscall to provide 473This call tries to make use of a native C<sendfile>-like syscall to
428zero-copy operation. For this to work, C<$out_fh> should refer to a 474provide zero-copy operation. For this to work, C<$out_fh> should refer to
429socket, and C<$in_fh> should refer to an mmap'able file. 475a socket, and C<$in_fh> should refer to an mmap'able file.
430 476
431If a native sendfile cannot be found or it fails with C<ENOSYS>, 477If a native sendfile cannot be found or it fails with C<ENOSYS>,
432C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>, 478C<EINVAL>, C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or
433it will be emulated, so you can call C<aio_sendfile> on any type of 479C<ENOTSOCK>, it will be emulated, so you can call C<aio_sendfile> on any
434filehandle regardless of the limitations of the operating system. 480type of filehandle regardless of the limitations of the operating system.
435 481
436Please note, however, that C<aio_sendfile> can read more bytes from 482As native sendfile syscalls (as practically any non-POSIX interface hacked
437C<$in_fh> than are written, and there is no way to find out how many 483together in a hurry to improve benchmark numbers) tend to be rather buggy
438bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only 484on many systems, this implementation tries to work around some known bugs
439provides the number of bytes written to C<$out_fh>. Only if the result 485in Linux and FreeBSD kernels (probably others, too), but that might fail,
440value equals C<$length> one can assume that C<$length> bytes have been 486so you really really should check the return value of C<aio_sendfile> -
441read. 487fewre bytes than expected might have been transferred.
442 488
443 489
444=item aio_readahead $fh,$offset,$length, $callback->($retval) 490=item aio_readahead $fh,$offset,$length, $callback->($retval)
445 491
446C<aio_readahead> populates the page cache with data from a file so that 492C<aio_readahead> populates the page cache with data from a file so that
… …
468for an explanation. 514for an explanation.
469 515
470Currently, the stats are always 64-bit-stats, i.e. instead of returning an 516Currently, the stats are always 64-bit-stats, i.e. instead of returning an
471error when stat'ing a large file, the results will be silently truncated 517error when stat'ing a large file, the results will be silently truncated
472unless perl itself is compiled with large file support. 518unless perl itself is compiled with large file support.
519
520To help interpret the mode and dev/rdev stat values, IO::AIO offers the
521following constants and functions (if not implemented, the constants will
522be C<0> and the functions will either C<croak> or fall back on traditional
523behaviour).
524
525C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
526C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
527C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
473 528
474Example: Print the length of F</etc/passwd>: 529Example: Print the length of F</etc/passwd>:
475 530
476 aio_stat "/etc/passwd", sub { 531 aio_stat "/etc/passwd", sub {
477 $_[0] and die "stat failed: $!"; 532 $_[0] and die "stat failed: $!";
… …
569 624
570Asynchronously unlink (delete) a file and call the callback with the 625Asynchronously unlink (delete) a file and call the callback with the
571result code. 626result code.
572 627
573 628
574=item aio_mknod $path, $mode, $dev, $callback->($status) 629=item aio_mknod $pathname, $mode, $dev, $callback->($status)
575 630
576[EXPERIMENTAL] 631[EXPERIMENTAL]
577 632
578Asynchronously create a device node (or fifo). See mknod(2). 633Asynchronously create a device node (or fifo). See mknod(2).
579 634
580The only (POSIX-) portable way of calling this function is: 635The only (POSIX-) portable way of calling this function is:
581 636
582 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 637 aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
583 638
639See C<aio_stat> for info about some potentially helpful extra constants
640and functions.
584 641
585=item aio_link $srcpath, $dstpath, $callback->($status) 642=item aio_link $srcpath, $dstpath, $callback->($status)
586 643
587Asynchronously create a new link to the existing object at C<$srcpath> at 644Asynchronously create a new link to the existing object at C<$srcpath> at
588the path C<$dstpath> and call the callback with the result code. 645the path C<$dstpath> and call the callback with the result code.
… …
592 649
593Asynchronously create a new symbolic link to the existing object at C<$srcpath> at 650Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
594the path C<$dstpath> and call the callback with the result code. 651the path C<$dstpath> and call the callback with the result code.
595 652
596 653
597=item aio_readlink $path, $callback->($link) 654=item aio_readlink $pathname, $callback->($link)
598 655
599Asynchronously read the symlink specified by C<$path> and pass it to 656Asynchronously read the symlink specified by C<$path> and pass it to
600the callback. If an error occurs, nothing or undef gets passed to the 657the callback. If an error occurs, nothing or undef gets passed to the
601callback. 658callback.
602 659
603 660
661=item aio_realpath $pathname, $callback->($path)
662
663Asynchronously make the path absolute and resolve any symlinks in
664C<$path>. The resulting path only consists of directories (Same as
665L<Cwd::realpath>).
666
667This request can be used to get the absolute path of the current working
668directory by passing it a path of F<.> (a single dot).
669
670
604=item aio_rename $srcpath, $dstpath, $callback->($status) 671=item aio_rename $srcpath, $dstpath, $callback->($status)
605 672
606Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 673Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
607rename(2) and call the callback with the result code. 674rename(2) and call the callback with the result code.
608 675
… …
630array-ref with the filenames. 697array-ref with the filenames.
631 698
632 699
633=item aio_readdirx $pathname, $flags, $callback->($entries, $flags) 700=item aio_readdirx $pathname, $flags, $callback->($entries, $flags)
634 701
635Quite similar to C<aio_readdir>, but the C<$flags> argument allows to tune 702Quite similar to C<aio_readdir>, but the C<$flags> argument allows one to
636behaviour and output format. In case of an error, C<$entries> will be 703tune behaviour and output format. In case of an error, C<$entries> will be
637C<undef>. 704C<undef>.
638 705
639The flags are a combination of the following constants, ORed together (the 706The flags are a combination of the following constants, ORed together (the
640flags will also be passed to the callback, possibly modified): 707flags will also be passed to the callback, possibly modified):
641 708
642=over 4 709=over 4
643 710
644=item IO::AIO::READDIR_DENTS 711=item IO::AIO::READDIR_DENTS
645 712
646When this flag is off, then the callback gets an arrayref with of names 713When this flag is off, then the callback gets an arrayref consisting of
647only (as with C<aio_readdir>), otherwise it gets an arrayref with 714names only (as with C<aio_readdir>), otherwise it gets an arrayref with
648C<[$name, $type, $inode]> arrayrefs, each describing a single directory 715C<[$name, $type, $inode]> arrayrefs, each describing a single directory
649entry in more detail. 716entry in more detail.
650 717
651C<$name> is the name of the entry. 718C<$name> is the name of the entry.
652 719
… …
665systems that do not deliver the inode information. 732systems that do not deliver the inode information.
666 733
667=item IO::AIO::READDIR_DIRS_FIRST 734=item IO::AIO::READDIR_DIRS_FIRST
668 735
669When this flag is set, then the names will be returned in an order where 736When this flag is set, then the names will be returned in an order where
670likely directories come first. This is useful when you need to quickly 737likely directories come first, in optimal stat order. This is useful when
671find directories, or you want to find all directories while avoiding to 738you need to quickly find directories, or you want to find all directories
672stat() each entry. 739while avoiding to stat() each entry.
673 740
674If the system returns type information in readdir, then this is used 741If the system returns type information in readdir, then this is used
675to find directories directly. Otherwise, likely directories are files 742to find directories directly. Otherwise, likely directories are names
676beginning with ".", or otherwise files with no dots, of which files with 743beginning with ".", or otherwise names with no dots, of which names with
677short names are tried first. 744short names are tried first.
678 745
679=item IO::AIO::READDIR_STAT_ORDER 746=item IO::AIO::READDIR_STAT_ORDER
680 747
681When this flag is set, then the names will be returned in an order 748When this flag is set, then the names will be returned in an order
… …
688 755
689=item IO::AIO::READDIR_FOUND_UNKNOWN 756=item IO::AIO::READDIR_FOUND_UNKNOWN
690 757
691This flag should not be set when calling C<aio_readdirx>. Instead, it 758This flag should not be set when calling C<aio_readdirx>. Instead, it
692is being set by C<aio_readdirx>, when any of the C<$type>'s found were 759is being set by C<aio_readdirx>, when any of the C<$type>'s found were
693C<IO::AIO::DT_UNKNOWN>. The absense of this flag therefore indicates that all 760C<IO::AIO::DT_UNKNOWN>. The absence of this flag therefore indicates that all
694C<$type>'s are known, which can be used to speed up some algorithms. 761C<$type>'s are known, which can be used to speed up some algorithms.
695 762
696=back 763=back
697 764
698 765
699=item aio_load $path, $data, $callback->($status) 766=item aio_load $pathname, $data, $callback->($status)
700 767
701This is a composite request that tries to fully load the given file into 768This is a composite request that tries to fully load the given file into
702memory. Status is the same as with aio_read. 769memory. Status is the same as with aio_read.
703 770
704=cut 771=cut
… …
826 if ($_[0] && $! == EXDEV) { 893 if ($_[0] && $! == EXDEV) {
827 aioreq_pri $pri; 894 aioreq_pri $pri;
828 add $grp aio_copy $src, $dst, sub { 895 add $grp aio_copy $src, $dst, sub {
829 $grp->result ($_[0]); 896 $grp->result ($_[0]);
830 897
831 if (!$_[0]) { 898 unless ($_[0]) {
832 aioreq_pri $pri; 899 aioreq_pri $pri;
833 add $grp aio_unlink $src; 900 add $grp aio_unlink $src;
834 } 901 }
835 }; 902 };
836 } else { 903 } else {
… …
839 }; 906 };
840 907
841 $grp 908 $grp
842} 909}
843 910
844=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 911=item aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
845 912
846Scans a directory (similar to C<aio_readdir>) but additionally tries to 913Scans a directory (similar to C<aio_readdir>) but additionally tries to
847efficiently separate the entries of directory C<$path> into two sets of 914efficiently separate the entries of directory C<$path> into two sets of
848names, directories you can recurse into (directories), and ones you cannot 915names, directories you can recurse into (directories), and ones you cannot
849recurse into (everything else, including symlinks to directories). 916recurse into (everything else, including symlinks to directories).
… …
880Then entries will be sorted into likely directories a non-initial dot 947Then entries will be sorted into likely directories a non-initial dot
881currently) and likely non-directories (see C<aio_readdirx>). Then every 948currently) and likely non-directories (see C<aio_readdirx>). Then every
882entry plus an appended C</.> will be C<stat>'ed, likely directories first, 949entry plus an appended C</.> will be C<stat>'ed, likely directories first,
883in order of their inode numbers. If that succeeds, it assumes that the 950in order of their inode numbers. If that succeeds, it assumes that the
884entry is a directory or a symlink to directory (which will be checked 951entry is a directory or a symlink to directory (which will be checked
885seperately). This is often faster than stat'ing the entry itself because 952separately). This is often faster than stat'ing the entry itself because
886filesystems might detect the type of the entry without reading the inode 953filesystems might detect the type of the entry without reading the inode
887data (e.g. ext2fs filetype feature), even on systems that cannot return 954data (e.g. ext2fs filetype feature), even on systems that cannot return
888the filetype information on readdir. 955the filetype information on readdir.
889 956
890If the known number of directories (link count - 2) has been reached, the 957If the known number of directories (link count - 2) has been reached, the
… …
906 973
907 my $grp = aio_group $cb; 974 my $grp = aio_group $cb;
908 975
909 $maxreq = 4 if $maxreq <= 0; 976 $maxreq = 4 if $maxreq <= 0;
910 977
911 # stat once 978 # get a wd object
912 aioreq_pri $pri; 979 aioreq_pri $pri;
913 add $grp aio_stat $path, sub { 980 add $grp aio_wd $path, sub {
981 $_[0]
914 return $grp->result () if $_[0]; 982 or return $grp->result ();
915 my $now = time;
916 my $hash1 = join ":", (stat _)[0,1,3,7,9];
917 983
918 # read the directory entries 984 my $wd = [shift, "."];
985
986 # stat once
919 aioreq_pri $pri; 987 aioreq_pri $pri;
920 add $grp aio_readdirx $path, READDIR_DIRS_FIRST, sub { 988 add $grp aio_stat $wd, sub {
921 my $entries = shift
922 or return $grp->result (); 989 return $grp->result () if $_[0];
990 my $now = time;
991 my $hash1 = join ":", (stat _)[0,1,3,7,9];
923 992
924 # stat the dir another time 993 # read the directory entries
925 aioreq_pri $pri; 994 aioreq_pri $pri;
995 add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {
996 my $entries = shift
997 or return $grp->result ();
998
999 # stat the dir another time
1000 aioreq_pri $pri;
926 add $grp aio_stat $path, sub { 1001 add $grp aio_stat $wd, sub {
927 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 1002 my $hash2 = join ":", (stat _)[0,1,3,7,9];
928 1003
929 my $ndirs; 1004 my $ndirs;
930 1005
931 # take the slow route if anything looks fishy 1006 # take the slow route if anything looks fishy
932 if ($hash1 ne $hash2 or (stat _)[9] == $now) { 1007 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
933 $ndirs = -1; 1008 $ndirs = -1;
934 } else { 1009 } else {
935 # if nlink == 2, we are finished 1010 # if nlink == 2, we are finished
936 # for non-posix-fs's, we rely on nlink < 2 1011 # for non-posix-fs's, we rely on nlink < 2
937 $ndirs = (stat _)[3] - 2 1012 $ndirs = (stat _)[3] - 2
938 or return $grp->result ([], $entries); 1013 or return $grp->result ([], $entries);
939 } 1014 }
940 1015
941 my (@dirs, @nondirs); 1016 my (@dirs, @nondirs);
942 1017
943 my $statgrp = add $grp aio_group sub { 1018 my $statgrp = add $grp aio_group sub {
944 $grp->result (\@dirs, \@nondirs); 1019 $grp->result (\@dirs, \@nondirs);
945 }; 1020 };
946 1021
947 limit $statgrp $maxreq; 1022 limit $statgrp $maxreq;
948 feed $statgrp sub { 1023 feed $statgrp sub {
949 return unless @$entries; 1024 return unless @$entries;
950 my $entry = shift @$entries; 1025 my $entry = shift @$entries;
951 1026
952 aioreq_pri $pri; 1027 aioreq_pri $pri;
1028 $wd->[1] = "$entry/.";
953 add $statgrp aio_stat "$path/$entry/.", sub { 1029 add $statgrp aio_stat $wd, sub {
954 if ($_[0] < 0) { 1030 if ($_[0] < 0) {
955 push @nondirs, $entry; 1031 push @nondirs, $entry;
956 } else { 1032 } else {
957 # need to check for real directory 1033 # need to check for real directory
958 aioreq_pri $pri; 1034 aioreq_pri $pri;
1035 $wd->[1] = $entry;
959 add $statgrp aio_lstat "$path/$entry", sub { 1036 add $statgrp aio_lstat $wd, sub {
960 if (-d _) { 1037 if (-d _) {
961 push @dirs, $entry; 1038 push @dirs, $entry;
962 1039
963 unless (--$ndirs) { 1040 unless (--$ndirs) {
964 push @nondirs, @$entries; 1041 push @nondirs, @$entries;
965 feed $statgrp; 1042 feed $statgrp;
1043 }
1044 } else {
1045 push @nondirs, $entry;
966 } 1046 }
967 } else {
968 push @nondirs, $entry;
969 } 1047 }
970 } 1048 }
971 } 1049 };
972 }; 1050 };
973 }; 1051 };
974 }; 1052 };
975 }; 1053 };
976 }; 1054 };
977 1055
978 $grp 1056 $grp
979} 1057}
980 1058
981=item aio_rmtree $path, $callback->($status) 1059=item aio_rmtree $pathname, $callback->($status)
982 1060
983Delete a directory tree starting (and including) C<$path>, return the 1061Delete a directory tree starting (and including) C<$path>, return the
984status of the final C<rmdir> only. This is a composite request that 1062status of the final C<rmdir> only. This is a composite request that
985uses C<aio_scandir> to recurse into and rmdir directories, and unlink 1063uses C<aio_scandir> to recurse into and rmdir directories, and unlink
986everything else. 1064everything else.
… …
1028callback with the fdatasync result code. 1106callback with the fdatasync result code.
1029 1107
1030If this call isn't available because your OS lacks it or it couldn't be 1108If this call isn't available because your OS lacks it or it couldn't be
1031detected, it will be emulated by calling C<fsync> instead. 1109detected, it will be emulated by calling C<fsync> instead.
1032 1110
1111=item aio_syncfs $fh, $callback->($status)
1112
1113Asynchronously call the syncfs syscall to sync the filesystem associated
1114to the given filehandle and call the callback with the syncfs result
1115code. If syncfs is not available, calls sync(), but returns C<-1> and sets
1116errno to C<ENOSYS> nevertheless.
1117
1033=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 1118=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
1034 1119
1035Sync the data portion of the file specified by C<$offset> and C<$length> 1120Sync the data portion of the file specified by C<$offset> and C<$length>
1036to disk (but NOT the metadata), by calling the Linux-specific 1121to disk (but NOT the metadata), by calling the Linux-specific
1037sync_file_range call. If sync_file_range is not available or it returns 1122sync_file_range call. If sync_file_range is not available or it returns
… …
1040C<$flags> can be a combination of C<IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE>, 1125C<$flags> can be a combination of C<IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE>,
1041C<IO::AIO::SYNC_FILE_RANGE_WRITE> and 1126C<IO::AIO::SYNC_FILE_RANGE_WRITE> and
1042C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range 1127C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range
1043manpage for details. 1128manpage for details.
1044 1129
1045=item aio_pathsync $path, $callback->($status) 1130=item aio_pathsync $pathname, $callback->($status)
1046 1131
1047This request tries to open, fsync and close the given path. This is a 1132This request tries to open, fsync and close the given path. This is a
1048composite request intended to sync directories after directory operations 1133composite request intended to sync directories after directory operations
1049(E.g. rename). This might not work on all operating systems or have any 1134(E.g. rename). This might not work on all operating systems or have any
1050specific effect, but usually it makes sure that directory changes get 1135specific effect, but usually it makes sure that directory changes get
… …
1108as for C<aio_msync>, above, except for flags, which must be either 1193as for C<aio_msync>, above, except for flags, which must be either
1109C<0> (which reads all pages and ensures they are instantiated) or 1194C<0> (which reads all pages and ensures they are instantiated) or
1110C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and 1195C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and
1111writing an octet from it, which dirties the page). 1196writing an octet from it, which dirties the page).
1112 1197
1198=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1199
1200This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1201scalars.
1202
1203It reads in all the pages of the underlying storage into memory (if any)
1204and locks them, so they are not getting swapped/paged out or removed.
1205
1206If C<$length> is undefined, then the scalar will be locked till the end.
1207
1208On systems that do not implement C<mlock>, this function returns C<-1>
1209and sets errno to C<ENOSYS>.
1210
1211Note that the corresponding C<munlock> is synchronous and is
1212documented under L<MISCELLANEOUS FUNCTIONS>.
1213
1214Example: open a file, mmap and mlock it - both will be undone when
1215C<$data> gets destroyed.
1216
1217 open my $fh, "<", $path or die "$path: $!";
1218 my $data;
1219 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1220 aio_mlock $data; # mlock in background
1221
1222=item aio_mlockall $flags, $callback->($status)
1223
1224Calls the C<mlockall> function with the given C<$flags> (a combination of
1225C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
1226
1227On systems that do not implement C<mlockall>, this function returns C<-1>
1228and sets errno to C<ENOSYS>.
1229
1230Note that the corresponding C<munlockall> is synchronous and is
1231documented under L<MISCELLANEOUS FUNCTIONS>.
1232
1233Example: asynchronously lock all current and future pages into memory.
1234
1235 aio_mlockall IO::AIO::MCL_FUTURE;
1236
1113=item aio_group $callback->(...) 1237=item aio_group $callback->(...)
1114 1238
1115This is a very special aio request: Instead of doing something, it is a 1239This is a very special aio request: Instead of doing something, it is a
1116container for other aio requests, which is useful if you want to bundle 1240container for other aio requests, which is useful if you want to bundle
1117many requests into a single, composite, request with a definite callback 1241many requests into a single, composite, request with a definite callback
… …
1153like sleep and file handle readable/writable, the overhead this creates is 1277like sleep and file handle readable/writable, the overhead this creates is
1154immense (it blocks a thread for a long time) so do not use this function 1278immense (it blocks a thread for a long time) so do not use this function
1155except to put your application under artificial I/O pressure. 1279except to put your application under artificial I/O pressure.
1156 1280
1157=back 1281=back
1282
1283
1284=head2 IO::AIO::WD - multiple working directories
1285
1286Your process only has one current working directory, which is used by all
1287threads. This makes it hard to use relative paths (some other component
1288could call C<chdir> at any time, and it is hard to control when the path
1289will be used by IO::AIO).
1290
1291One solution for this is to always use absolute paths. This usually works,
1292but can be quite slow (the kernel has to walk the whole path on every
1293access), and can also be a hassle to implement.
1294
1295Newer POSIX systems have a number of functions (openat, fdopendir,
1296futimensat and so on) that make it possible to specify working directories
1297per operation.
1298
1299For portability, and because the clowns who "designed", or shall I write,
1300perpetrated this new interface were obviously half-drunk, this abstraction
1301cannot be perfect, though.
1302
1303IO::AIO allows you to convert directory paths into a so-called IO::AIO::WD
1304object. This object stores the canonicalised, absolute version of the
1305path, and on systems that allow it, also a directory file descriptor.
1306
1307Everywhere where a pathname is accepted by IO::AIO (e.g. in C<aio_stat>
1308or C<aio_unlink>), one can specify an array reference with an IO::AIO::WD
1309object and a pathname instead (or the IO::AIO::WD object alone, which
1310gets interpreted as C<[$wd, "."]>). If the pathname is absolute, the
1311IO::AIO::WD object is ignored, otherwise the pathname is resolved relative
1312to that IO::AIO::WD object.
1313
1314For example, to get a wd object for F</etc> and then stat F<passwd>
1315inside, you would write:
1316
1317 aio_wd "/etc", sub {
1318 my $etcdir = shift;
1319
1320 # although $etcdir can be undef on error, there is generally no reason
1321 # to check for errors here, as aio_stat will fail with ENOENT
1322 # when $etcdir is undef.
1323
1324 aio_stat [$etcdir, "passwd"], sub {
1325 # yay
1326 };
1327 };
1328
1329That C<aio_wd> is a request and not a normal function shows that creating
1330an IO::AIO::WD object is itself a potentially blocking operation, which is
1331why it is done asynchronously.
1332
1333To stat the directory obtained with C<aio_wd> above, one could write
1334either of the following three request calls:
1335
1336 aio_lstat "/etc" , sub { ... # pathname as normal string
1337 aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
1338 aio_lstat $wd , sub { ... # shorthand for the previous
1339
1340As with normal pathnames, IO::AIO keeps a copy of the working directory
1341object and the pathname string, so you could write the following without
1342causing any issues due to C<$path> getting reused:
1343
1344 my $path = [$wd, undef];
1345
1346 for my $name (qw(abc def ghi)) {
1347 $path->[1] = $name;
1348 aio_stat $path, sub {
1349 # ...
1350 };
1351 }
1352
1353There are some caveats: when directories get renamed (or deleted), the
1354pathname string doesn't change, so will point to the new directory (or
1355nowhere at all), while the directory fd, if available on the system,
1356will still point to the original directory. Most functions accepting a
1357pathname will use the directory fd on newer systems, and the string on
1358older systems. Some functions (such as realpath) will always rely on the
1359string form of the pathname.
1360
1361So this fucntionality is mainly useful to get some protection against
1362C<chdir>, to easily get an absolute path out of a relative path for future
1363reference, and to speed up doing many operations in the same directory
1364(e.g. when stat'ing all files in a directory).
1365
1366The following functions implement this working directory abstraction:
1367
1368=over 4
1369
1370=item aio_wd $pathname, $callback->($wd)
1371
1372Asynchonously canonicalise the given pathname and convert it to an
1373IO::AIO::WD object representing it. If possible and supported on the
1374system, also open a directory fd to speed up pathname resolution relative
1375to this working directory.
1376
1377If something goes wrong, then C<undef> is passwd to the callback instead
1378of a working directory object and C<$!> is set appropriately. Since
1379passing C<undef> as working directory component of a pathname fails the
1380request with C<ENOENT>, there is often no need for error checking in the
1381C<aio_wd> callback, as future requests using the value will fail in the
1382expected way.
1383
1384If this call isn't available because your OS lacks it or it couldn't be
1385detected, it will be emulated by calling C<fsync> instead.
1386
1387=item IO::AIO::CWD
1388
1389This is a compiletime constant (object) that represents the process
1390current working directory.
1391
1392Specifying this object as working directory object for a pathname is as
1393if the pathname would be specified directly, without a directory object,
1394e.g., these calls are functionally identical:
1395
1396 aio_stat "somefile", sub { ... };
1397 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1398
1399=back
1400
1158 1401
1159=head2 IO::AIO::REQ CLASS 1402=head2 IO::AIO::REQ CLASS
1160 1403
1161All non-aggregate C<aio_*> functions return an object of this class when 1404All non-aggregate C<aio_*> functions return an object of this class when
1162called in non-void context. 1405called in non-void context.
… …
1280 1523
1281Sets a feeder/generator on this group: every group can have an attached 1524Sets a feeder/generator on this group: every group can have an attached
1282generator that generates requests if idle. The idea behind this is that, 1525generator that generates requests if idle. The idea behind this is that,
1283although you could just queue as many requests as you want in a group, 1526although you could just queue as many requests as you want in a group,
1284this might starve other requests for a potentially long time. For example, 1527this might starve other requests for a potentially long time. For example,
1285C<aio_scandir> might generate hundreds of thousands C<aio_stat> requests, 1528C<aio_scandir> might generate hundreds of thousands of C<aio_stat>
1286delaying any later requests for a long time. 1529requests, delaying any later requests for a long time.
1287 1530
1288To avoid this, and allow incremental generation of requests, you can 1531To avoid this, and allow incremental generation of requests, you can
1289instead a group and set a feeder on it that generates those requests. The 1532instead a group and set a feeder on it that generates those requests. The
1290feed callback will be called whenever there are few enough (see C<limit>, 1533feed callback will be called whenever there are few enough (see C<limit>,
1291below) requests active in the group itself and is expected to queue more 1534below) requests active in the group itself and is expected to queue more
… …
1340 1583
1341See C<poll_cb> for an example. 1584See C<poll_cb> for an example.
1342 1585
1343=item IO::AIO::poll_cb 1586=item IO::AIO::poll_cb
1344 1587
1345Process some outstanding events on the result pipe. You have to call this 1588Process some outstanding events on the result pipe. You have to call
1346regularly. Returns C<0> if all events could be processed, or C<-1> if it 1589this regularly. Returns C<0> if all events could be processed (or there
1347returned earlier for whatever reason. Returns immediately when no events 1590were no events to process), or C<-1> if it returned earlier for whatever
1348are outstanding. The amount of events processed depends on the settings of 1591reason. Returns immediately when no events are outstanding. The amount of
1349C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>. 1592events processed depends on the settings of C<IO::AIO::max_poll_req> and
1593C<IO::AIO::max_poll_time>.
1350 1594
1351If not all requests were processed for whatever reason, the filehandle 1595If not all requests were processed for whatever reason, the filehandle
1352will still be ready when C<poll_cb> returns, so normally you don't have to 1596will still be ready when C<poll_cb> returns, so normally you don't have to
1353do anything special to have it called later. 1597do anything special to have it called later.
1598
1599Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
1600ready, it can be beneficial to call this function from loops which submit
1601a lot of requests, to make sure the results get processed when they become
1602available and not just when the loop is finished and the event loop takes
1603over again. This function returns very fast when there are no outstanding
1604requests.
1354 1605
1355Example: Install an Event watcher that automatically calls 1606Example: Install an Event watcher that automatically calls
1356IO::AIO::poll_cb with high priority (more examples can be found in the 1607IO::AIO::poll_cb with high priority (more examples can be found in the
1357SYNOPSIS section, at the top of this document): 1608SYNOPSIS section, at the top of this document):
1358 1609
… …
1460 1711
1461Under normal circumstances you don't need to call this function. 1712Under normal circumstances you don't need to call this function.
1462 1713
1463=item IO::AIO::max_idle $nthreads 1714=item IO::AIO::max_idle $nthreads
1464 1715
1465Limit the number of threads (default: 4) that are allowed to idle (i.e., 1716Limit the number of threads (default: 4) that are allowed to idle
1466threads that did not get a request to process within 10 seconds). That 1717(i.e., threads that did not get a request to process within the idle
1467means if a thread becomes idle while C<$nthreads> other threads are also 1718timeout (default: 10 seconds). That means if a thread becomes idle while
1468idle, it will free its resources and exit. 1719C<$nthreads> other threads are also idle, it will free its resources and
1720exit.
1469 1721
1470This is useful when you allow a large number of threads (e.g. 100 or 1000) 1722This is useful when you allow a large number of threads (e.g. 100 or 1000)
1471to allow for extremely high load situations, but want to free resources 1723to allow for extremely high load situations, but want to free resources
1472under normal circumstances (1000 threads can easily consume 30MB of RAM). 1724under normal circumstances (1000 threads can easily consume 30MB of RAM).
1473 1725
1474The default is probably ok in most situations, especially if thread 1726The default is probably ok in most situations, especially if thread
1475creation is fast. If thread creation is very slow on your system you might 1727creation is fast. If thread creation is very slow on your system you might
1476want to use larger values. 1728want to use larger values.
1477 1729
1730=item IO::AIO::idle_timeout $seconds
1731
1732Sets the minimum idle timeout (default 10) after which worker threads are
1733allowed to exit. SEe C<IO::AIO::max_idle>.
1734
1478=item IO::AIO::max_outstanding $maxreqs 1735=item IO::AIO::max_outstanding $maxreqs
1736
1737Sets the maximum number of outstanding requests to C<$nreqs>. If
1738you do queue up more than this number of requests, the next call to
1739C<IO::AIO::poll_cb> (and other functions calling C<poll_cb>, such as
1740C<IO::AIO::flush> or C<IO::AIO::poll>) will block until the limit is no
1741longer exceeded.
1742
1743In other words, this setting does not enforce a queue limit, but can be
1744used to make poll functions block if the limit is exceeded.
1479 1745
1480This is a very bad function to use in interactive programs because it 1746This is a very bad function to use in interactive programs because it
1481blocks, and a bad way to reduce concurrency because it is inexact: Better 1747blocks, and a bad way to reduce concurrency because it is inexact: Better
1482use an C<aio_group> together with a feed callback. 1748use an C<aio_group> together with a feed callback.
1483 1749
1484Sets the maximum number of outstanding requests to C<$nreqs>. If you 1750It's main use is in scripts without an event loop - when you want to stat
1485do queue up more than this number of requests, the next call to the 1751a lot of files, you can write somehting like this:
1486C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
1487function will block until the limit is no longer exceeded.
1488 1752
1489The default value is very large, so there is no practical limit on the 1753 IO::AIO::max_outstanding 32;
1490number of outstanding requests.
1491 1754
1492You can still queue as many requests as you want. Therefore, 1755 for my $path (...) {
1493C<max_outstanding> is mainly useful in simple scripts (with low values) or 1756 aio_stat $path , ...;
1494as a stop gap to shield against fatal memory overflow (with large values). 1757 IO::AIO::poll_cb;
1758 }
1759
1760 IO::AIO::flush;
1761
1762The call to C<poll_cb> inside the loop will normally return instantly, but
1763as soon as more thna C<32> reqeusts are in-flight, it will block until
1764some requests have been handled. This keeps the loop from pushing a large
1765number of C<aio_stat> requests onto the queue.
1766
1767The default value for C<max_outstanding> is very large, so there is no
1768practical limit on the number of outstanding requests.
1495 1769
1496=back 1770=back
1497 1771
1498=head3 STATISTICAL INFORMATION 1772=head3 STATISTICAL INFORMATION
1499 1773
… …
1537 1811
1538Returns the number of bytes copied, or C<-1> on error. 1812Returns the number of bytes copied, or C<-1> on error.
1539 1813
1540=item IO::AIO::fadvise $fh, $offset, $len, $advice 1814=item IO::AIO::fadvise $fh, $offset, $len, $advice
1541 1815
1542Simply calls the C<posix_fadvise> function (see it's 1816Simply calls the C<posix_fadvise> function (see its
1543manpage for details). The following advice constants are 1817manpage for details). The following advice constants are
1544avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>, 1818available: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1545C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>, 1819C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1546C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 1820C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1547 1821
1548On systems that do not implement C<posix_fadvise>, this function returns 1822On systems that do not implement C<posix_fadvise>, this function returns
1549ENOSYS, otherwise the return value of C<posix_fadvise>. 1823ENOSYS, otherwise the return value of C<posix_fadvise>.
1824
1825=item IO::AIO::madvise $scalar, $offset, $len, $advice
1826
1827Simply calls the C<posix_madvise> function (see its
1828manpage for details). The following advice constants are
1829available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
1830C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>.
1831
1832On systems that do not implement C<posix_madvise>, this function returns
1833ENOSYS, otherwise the return value of C<posix_madvise>.
1834
1835=item IO::AIO::mprotect $scalar, $offset, $len, $protect
1836
1837Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
1838$scalar (see its manpage for details). The following protect
1839constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
1840C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
1841
1842On systems that do not implement C<mprotect>, this function returns
1843ENOSYS, otherwise the return value of C<mprotect>.
1550 1844
1551=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 1845=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1552 1846
1553Memory-maps a file (or anonymous memory range) and attaches it to the 1847Memory-maps a file (or anonymous memory range) and attaches it to the
1554given C<$scalar>, which will act like a string scalar. 1848given C<$scalar>, which will act like a string scalar.
… …
1600 1894
1601=item IO::AIO::munmap $scalar 1895=item IO::AIO::munmap $scalar
1602 1896
1603Removes a previous mmap and undefines the C<$scalar>. 1897Removes a previous mmap and undefines the C<$scalar>.
1604 1898
1605=item IO::AIO::mlockall $flags 1899=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
1606 1900
1607Calls the C<mlockall> function with the given C<$flags> (a combination of 1901Calls the C<munlock> function, undoing the effects of a previous
1608C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>). 1902C<aio_mlock> call (see its description for details).
1609
1610On systems that do not implement C<mlockall>, this function returns
1611ENOSYS, otherwise the return value of C<mlockall>.
1612 1903
1613=item IO::AIO::munlockall 1904=item IO::AIO::munlockall
1614 1905
1615Calls the C<munlockall> function. 1906Calls the C<munlockall> function.
1616 1907
… …
1658 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno => 1949 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
1659 \&IO::AIO::poll_cb); 1950 \&IO::AIO::poll_cb);
1660 1951
1661=head2 FORK BEHAVIOUR 1952=head2 FORK BEHAVIOUR
1662 1953
1663This module should do "the right thing" when the process using it forks: 1954Usage of pthreads in a program changes the semantics of fork
1955considerably. Specifically, only async-safe functions can be called after
1956fork. Perl doesn't know about this, so in general, you cannot call fork
1957with defined behaviour in perl if pthreads are involved. IO::AIO uses
1958pthreads, so this applies, but many other extensions and (for inexplicable
1959reasons) perl itself often is linked against pthreads, so this limitation
1960applies to quite a lot of perls.
1664 1961
1665Before the fork, IO::AIO enters a quiescent state where no requests 1962This module no longer tries to fight your OS, or POSIX. That means IO::AIO
1666can be added in other threads and no results will be processed. After 1963only works in the process that loaded it. Forking is fully supported, but
1667the fork the parent simply leaves the quiescent state and continues 1964using IO::AIO in the child is not.
1668request/result processing, while the child frees the request/result queue
1669(so that the requests started before the fork will only be handled in the
1670parent). Threads will be started on demand until the limit set in the
1671parent process has been reached again.
1672 1965
1673In short: the parent will, after a short pause, continue as if fork had 1966You might get around by not I<using> IO::AIO before (or after)
1674not been called, while the child will act as if IO::AIO has not been used 1967forking. You could also try to call the L<IO::AIO::reinit> function in the
1675yet. 1968child:
1969
1970=over 4
1971
1972=item IO::AIO::reinit
1973
1974Abandons all current requests and I/O threads and simply reinitialises all
1975data structures. This is not an operation supported by any standards, but
1976happens to work on GNU/Linux and some newer BSD systems.
1977
1978The only reasonable use for this function is to call it after forking, if
1979C<IO::AIO> was used in the parent. Calling it while IO::AIO is active in
1980the process will result in undefined behaviour. Calling it at any time
1981will also result in any undefined (by POSIX) behaviour.
1982
1983=back
1676 1984
1677=head2 MEMORY USAGE 1985=head2 MEMORY USAGE
1678 1986
1679Per-request usage: 1987Per-request usage:
1680 1988

Diff Legend

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