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

Comparing IO-AIO/README (file contents):
Revision 1.41 by root, Sat Jan 2 14:24:32 2010 UTC vs.
Revision 1.48 by root, Wed Jun 29 11:25:17 2011 UTC

… …
2 IO::AIO - Asynchronous Input/Output 2 IO::AIO - Asynchronous Input/Output
3 3
4SYNOPSIS 4SYNOPSIS
5 use IO::AIO; 5 use IO::AIO;
6 6
7 aio_open "/etc/passwd", O_RDONLY, 0, sub { 7 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
8 my $fh = shift 8 my $fh = shift
9 or die "/etc/passwd: $!"; 9 or die "/etc/passwd: $!";
10 ... 10 ...
11 }; 11 };
12 12
… …
23 my $req = aio_unlink "/tmp/file", sub { }; 23 my $req = aio_unlink "/tmp/file", sub { };
24 $req->cancel; # cancel request if still in queue 24 $req->cancel; # cancel request if still in queue
25 25
26 my $grp = aio_group sub { print "all stats done\n" }; 26 my $grp = aio_group sub { print "all stats done\n" };
27 add $grp aio_stat "..." for ...; 27 add $grp aio_stat "..." for ...;
28
29 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
30 use AnyEvent::AIO;
31
32 # EV integration
33 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
34
35 # Event integration
36 Event->io (fd => IO::AIO::poll_fileno,
37 poll => 'r',
38 cb => \&IO::AIO::poll_cb);
39
40 # Glib/Gtk2 integration
41 add_watch Glib::IO IO::AIO::poll_fileno,
42 in => sub { IO::AIO::poll_cb; 1 };
43
44 # Tk integration
45 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
46 readable => \&IO::AIO::poll_cb);
47
48 # Danga::Socket integration
49 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
50 \&IO::AIO::poll_cb);
51 28
52DESCRIPTION 29DESCRIPTION
53 This module implements asynchronous I/O using whatever means your 30 This module implements asynchronous I/O using whatever means your
54 operating system supports. It is implemented as an interface to "libeio" 31 operating system supports. It is implemented as an interface to "libeio"
55 (<http://software.schmorp.de/pkg/libeio.html>). 32 (<http://software.schmorp.de/pkg/libeio.html>).
… …
95 72
96 # register the IO::AIO callback with EV 73 # register the IO::AIO callback with EV
97 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 74 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
98 75
99 # queue the request to open /etc/passwd 76 # queue the request to open /etc/passwd
100 aio_open "/etc/passwd", O_RDONLY, 0, sub { 77 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
101 my $fh = shift 78 my $fh = shift
102 or die "error while opening: $!"; 79 or die "error while opening: $!";
103 80
104 # stat'ing filehandles is generally non-blocking 81 # stat'ing filehandles is generally non-blocking
105 my $size = -s $fh; 82 my $size = -s $fh;
… …
168 anymore (except possibly for the Perl object, but its connection to 145 anymore (except possibly for the Perl object, but its connection to
169 the actual aio request is severed and calling its methods will 146 the actual aio request is severed and calling its methods will
170 either do nothing or result in a runtime error). 147 either do nothing or result in a runtime error).
171 148
172FUNCTIONS 149FUNCTIONS
150 QUICK OVERVIEW
151 This section simply lists the prototypes of the most important functions
152 for quick reference. See the following sections for function-by-function
153 documentation.
154
155 aio_open $pathname, $flags, $mode, $callback->($fh)
156 aio_close $fh, $callback->($status)
157 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
158 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
159 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
160 aio_readahead $fh,$offset,$length, $callback->($retval)
161 aio_stat $fh_or_path, $callback->($status)
162 aio_lstat $fh, $callback->($status)
163 aio_statvfs $fh_or_path, $callback->($statvfs)
164 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
165 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
166 aio_truncate $fh_or_path, $offset, $callback->($status)
167 aio_chmod $fh_or_path, $mode, $callback->($status)
168 aio_unlink $pathname, $callback->($status)
169 aio_mknod $path, $mode, $dev, $callback->($status)
170 aio_link $srcpath, $dstpath, $callback->($status)
171 aio_symlink $srcpath, $dstpath, $callback->($status)
172 aio_readlink $path, $callback->($link)
173 aio_rename $srcpath, $dstpath, $callback->($status)
174 aio_mkdir $pathname, $mode, $callback->($status)
175 aio_rmdir $pathname, $callback->($status)
176 aio_readdir $pathname, $callback->($entries)
177 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
178 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
179 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
180 aio_load $path, $data, $callback->($status)
181 aio_copy $srcpath, $dstpath, $callback->($status)
182 aio_move $srcpath, $dstpath, $callback->($status)
183 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
184 aio_rmtree $path, $callback->($status)
185 aio_sync $callback->($status)
186 aio_fsync $fh, $callback->($status)
187 aio_fdatasync $fh, $callback->($status)
188 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
189 aio_pathsync $path, $callback->($status)
190 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
191 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
192 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
193 aio_mlockall $flags, $callback->($status)
194 aio_group $callback->(...)
195 aio_nop $callback->()
196
197 $prev_pri = aioreq_pri [$pri]
198 aioreq_nice $pri_adjust
199
200 IO::AIO::poll_wait
201 IO::AIO::poll_cb
202 IO::AIO::poll
203 IO::AIO::flush
204 IO::AIO::max_poll_reqs $nreqs
205 IO::AIO::max_poll_time $seconds
206 IO::AIO::min_parallel $nthreads
207 IO::AIO::max_parallel $nthreads
208 IO::AIO::max_idle $nthreads
209 IO::AIO::idle_timeout $seconds
210 IO::AIO::max_outstanding $maxreqs
211 IO::AIO::nreqs
212 IO::AIO::nready
213 IO::AIO::npending
214
215 IO::AIO::sendfile $ofh, $ifh, $offset, $count
216 IO::AIO::fadvise $fh, $offset, $len, $advice
217 IO::AIO::madvise $scalar, $offset, $length, $advice
218 IO::AIO::mprotect $scalar, $offset, $length, $protect
219 IO::AIO::munlock $scalar, $offset = 0, $length = undef
220 IO::AIO::munlockall
221
173 AIO REQUEST FUNCTIONS 222 AIO REQUEST FUNCTIONS
174 All the "aio_*" calls are more or less thin wrappers around the syscall 223 All the "aio_*" calls are more or less thin wrappers around the syscall
175 with the same name (sans "aio_"). The arguments are similar or 224 with the same name (sans "aio_"). The arguments are similar or
176 identical, and they all accept an additional (and optional) $callback 225 identical, and they all accept an additional (and optional) $callback
177 argument which must be a code reference. This code reference will get 226 argument which must be a code reference. This code reference will get
… …
248 will be modified by the umask in effect then the request is being 297 will be modified by the umask in effect then the request is being
249 executed, so better never change the umask. 298 executed, so better never change the umask.
250 299
251 Example: 300 Example:
252 301
253 aio_open "/etc/passwd", O_RDONLY, 0, sub { 302 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
254 if ($_[0]) { 303 if ($_[0]) {
255 print "open successful, fh is $_[0]\n"; 304 print "open successful, fh is $_[0]\n";
256 ... 305 ...
257 } else { 306 } else {
258 die "open failed: $!\n"; 307 die "open failed: $!\n";
259 } 308 }
260 }; 309 };
261 310
311 In addition to all the common open modes/flags ("O_RDONLY",
312 "O_WRONLY", "O_RDWR", "O_CREAT", "O_TRUNC", "O_EXCL" and
313 "O_APPEND"), the following POSIX and non-POSIX constants are
314 available (missing ones on your system are, as usual, 0):
315
316 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
317 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
318 "O_DSYNC", "O_RSYNC", "O_SYNC" and "O_TTY_INIT".
319
262 aio_close $fh, $callback->($status) 320 aio_close $fh, $callback->($status)
263 Asynchronously close a file and call the callback with the result 321 Asynchronously close a file and call the callback with the result
264 code. 322 code.
265 323
266 Unfortunately, you can't do this to perl. Perl *insists* very 324 Unfortunately, you can't do this to perl. Perl *insists* very
… …
309 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 367 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
310 Tries to copy $length bytes from $in_fh to $out_fh. It starts 368 Tries to copy $length bytes from $in_fh to $out_fh. It starts
311 reading at byte offset $in_offset, and starts writing at the current 369 reading at byte offset $in_offset, and starts writing at the current
312 file offset of $out_fh. Because of that, it is not safe to issue 370 file offset of $out_fh. Because of that, it is not safe to issue
313 more than one "aio_sendfile" per $out_fh, as they will interfere 371 more than one "aio_sendfile" per $out_fh, as they will interfere
314 with each other. 372 with each other. The same $in_fh works fine though, as this function
373 does not move or use the file offset of $in_fh.
315 374
375 Please note that "aio_sendfile" can read more bytes from $in_fh than
376 are written, and there is no way to find out how many more bytes
377 have been read from "aio_sendfile" alone, as "aio_sendfile" only
378 provides the number of bytes written to $out_fh. Only if the result
379 value equals $length one can assume that $length bytes have been
380 read.
381
382 Unlike with other "aio_" functions, it makes a lot of sense to use
383 "aio_sendfile" on non-blocking sockets, as long as one end
384 (typically the $in_fh) is a file - the file I/O will then be
385 asynchronous, while the socket I/O will be non-blocking. Note,
386 however, that you can run into a trap where "aio_sendfile" reads
387 some data with readahead, then fails to write all data, and when the
388 socket is ready the next time, the data in the cache is already
389 lost, forcing "aio_sendfile" to again hit the disk. Explicit
390 "aio_read" + "aio_write" let's you better control resource usage.
391
316 This call tries to make use of a native "sendfile" syscall to 392 This call tries to make use of a native "sendfile"-like syscall to
317 provide zero-copy operation. For this to work, $out_fh should refer 393 provide zero-copy operation. For this to work, $out_fh should refer
318 to a socket, and $in_fh should refer to mmap'able file. 394 to a socket, and $in_fh should refer to an mmap'able file.
319 395
320 If a native sendfile cannot be found or it fails with "ENOSYS", 396 If a native sendfile cannot be found or it fails with "ENOSYS",
321 "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK", 397 "EINVAL", "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
322 it will be emulated, so you can call "aio_sendfile" on any type of 398 "ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
323 filehandle regardless of the limitations of the operating system. 399 any type of filehandle regardless of the limitations of the
400 operating system.
324 401
325 Please note, however, that "aio_sendfile" can read more bytes from 402 As native sendfile syscalls (as practically any non-POSIX interface
326 $in_fh than are written, and there is no way to find out how many 403 hacked together in a hurry to improve benchmark numbers) tend to be
327 bytes have been read from "aio_sendfile" alone, as "aio_sendfile" 404 rather buggy on many systems, this implementation tries to work
328 only provides the number of bytes written to $out_fh. Only if the 405 around some known bugs in Linux and FreeBSD kernels (probably
329 result value equals $length one can assume that $length bytes have 406 others, too), but that might fail, so you really really should check
330 been read. 407 the return value of "aio_sendfile" - fewre bytes than expected might
408 have been transferred.
331 409
332 aio_readahead $fh,$offset,$length, $callback->($retval) 410 aio_readahead $fh,$offset,$length, $callback->($retval)
333 "aio_readahead" populates the page cache with data from a file so 411 "aio_readahead" populates the page cache with data from a file so
334 that subsequent reads from that file will not block on disk I/O. The 412 that subsequent reads from that file will not block on disk I/O. The
335 $offset argument specifies the starting point from which data is to 413 $offset argument specifies the starting point from which data is to
… …
356 Currently, the stats are always 64-bit-stats, i.e. instead of 434 Currently, the stats are always 64-bit-stats, i.e. instead of
357 returning an error when stat'ing a large file, the results will be 435 returning an error when stat'ing a large file, the results will be
358 silently truncated unless perl itself is compiled with large file 436 silently truncated unless perl itself is compiled with large file
359 support. 437 support.
360 438
439 To help interpret the mode and dev/rdev stat values, IO::AIO offers
440 the following constants and functions (if not implemented, the
441 constants will be 0 and the functions will either "croak" or fall
442 back on traditional behaviour).
443
444 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
445 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
446 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
447
361 Example: Print the length of /etc/passwd: 448 Example: Print the length of /etc/passwd:
362 449
363 aio_stat "/etc/passwd", sub { 450 aio_stat "/etc/passwd", sub {
364 $_[0] and die "stat failed: $!"; 451 $_[0] and die "stat failed: $!";
365 print "size is ", -s _, "\n"; 452 print "size is ", -s _, "\n";
366 }; 453 };
367 454
455 aio_statvfs $fh_or_path, $callback->($statvfs)
456 Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
457 whether a file handle or path was passed.
458
459 On success, the callback is passed a hash reference with the
460 following members: "bsize", "frsize", "blocks", "bfree", "bavail",
461 "files", "ffree", "favail", "fsid", "flag" and "namemax". On
462 failure, "undef" is passed.
463
464 The following POSIX IO::AIO::ST_* constants are defined: "ST_RDONLY"
465 and "ST_NOSUID".
466
467 The following non-POSIX IO::AIO::ST_* flag masks are defined to
468 their correct value when available, or to 0 on systems that do not
469 support them: "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
470 "ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
471 "ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
472
473 Example: stat "/wd" and dump out the data if successful.
474
475 aio_statvfs "/wd", sub {
476 my $f = $_[0]
477 or die "statvfs: $!";
478
479 use Data::Dumper;
480 say Dumper $f;
481 };
482
483 # result:
484 {
485 bsize => 1024,
486 bfree => 4333064312,
487 blocks => 10253828096,
488 files => 2050765568,
489 flag => 4096,
490 favail => 2042092649,
491 bavail => 4333064312,
492 ffree => 2042092649,
493 namemax => 255,
494 frsize => 1024,
495 fsid => 1810
496 }
497
368 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 498 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
369 Works like perl's "utime" function (including the special case of 499 Works like perl's "utime" function (including the special case of
370 $atime and $mtime being undef). Fractional times are supported if 500 $atime and $mtime being undef). Fractional times are supported if
371 the underlying syscalls support them. 501 the underlying syscalls support them.
372 502
… …
410 540
411 The only (POSIX-) portable way of calling this function is: 541 The only (POSIX-) portable way of calling this function is:
412 542
413 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 543 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
414 544
545 See "aio_stat" for info about some potentially helpful extra
546 constants and functions.
547
415 aio_link $srcpath, $dstpath, $callback->($status) 548 aio_link $srcpath, $dstpath, $callback->($status)
416 Asynchronously create a new link to the existing object at $srcpath 549 Asynchronously create a new link to the existing object at $srcpath
417 at the path $dstpath and call the callback with the result code. 550 at the path $dstpath and call the callback with the result code.
418 551
419 aio_symlink $srcpath, $dstpath, $callback->($status) 552 aio_symlink $srcpath, $dstpath, $callback->($status)
… …
455 The flags are a combination of the following constants, ORed 588 The flags are a combination of the following constants, ORed
456 together (the flags will also be passed to the callback, possibly 589 together (the flags will also be passed to the callback, possibly
457 modified): 590 modified):
458 591
459 IO::AIO::READDIR_DENTS 592 IO::AIO::READDIR_DENTS
460 When this flag is off, then the callback gets an arrayref with 593 When this flag is off, then the callback gets an arrayref
461 of names only (as with "aio_readdir"), otherwise it gets an 594 consisting of names only (as with "aio_readdir"), otherwise it
462 arrayref with "[$name, $type, $inode]" arrayrefs, each 595 gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
463 describing a single directory entry in more detail. 596 describing a single directory entry in more detail.
464 597
465 $name is the name of the entry. 598 $name is the name of the entry.
466 599
467 $type is one of the "IO::AIO::DT_xxx" constants: 600 $type is one of the "IO::AIO::DT_xxx" constants:
… …
480 unspecified content on systems that do not deliver the inode 613 unspecified content on systems that do not deliver the inode
481 information. 614 information.
482 615
483 IO::AIO::READDIR_DIRS_FIRST 616 IO::AIO::READDIR_DIRS_FIRST
484 When this flag is set, then the names will be returned in an 617 When this flag is set, then the names will be returned in an
485 order where likely directories come first. This is useful when 618 order where likely directories come first, in optimal stat
486 you need to quickly find directories, or you want to find all 619 order. This is useful when you need to quickly find directories,
487 directories while avoiding to stat() each entry. 620 or you want to find all directories while avoiding to stat()
621 each entry.
488 622
489 If the system returns type information in readdir, then this is 623 If the system returns type information in readdir, then this is
490 used to find directories directly. Otherwise, likely directories 624 used to find directories directly. Otherwise, likely directories
491 are files beginning with ".", or otherwise files with no dots, 625 are names beginning with ".", or otherwise names with no dots,
492 of which files with short names are tried first. 626 of which names with short names are tried first.
493 627
494 IO::AIO::READDIR_STAT_ORDER 628 IO::AIO::READDIR_STAT_ORDER
495 When this flag is set, then the names will be returned in an 629 When this flag is set, then the names will be returned in an
496 order suitable for stat()'ing each one. That is, when you plan 630 order suitable for stat()'ing each one. That is, when you plan
497 to stat() all files in the given directory, then the returned 631 to stat() all files in the given directory, then the returned
… …
640 Passes 0 when everything went ok, and -1 on error. 774 Passes 0 when everything went ok, and -1 on error.
641 775
642 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, 776 aio_msync $scalar, $offset = 0, $length = undef, flags = 0,
643 $callback->($status) 777 $callback->($status)
644 This is a rather advanced IO::AIO call, which only works on 778 This is a rather advanced IO::AIO call, which only works on
645 mmap(2)ed scalars (see the Sys::Mmap or Mmap modules for details on 779 mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
780 also works on data scalars managed by the Sys::Mmap or Mmap modules,
646 this, note that the scalar must only be modified in-place while an 781 note that the scalar must only be modified in-place while an aio
647 aio operation is pending on it). 782 operation is pending on it).
648 783
649 It calls the "msync" function of your OS, if available, with the 784 It calls the "msync" function of your OS, if available, with the
650 memory area starting at $offset in the string and ending $length 785 memory area starting at $offset in the string and ending $length
651 bytes later. If $length is negative, counts from the end, and if 786 bytes later. If $length is negative, counts from the end, and if
652 $length is "undef", then it goes till the end of the string. The 787 $length is "undef", then it goes till the end of the string. The
… …
662 inside the scalar. All caveats and parameters are the same as for 797 inside the scalar. All caveats and parameters are the same as for
663 "aio_msync", above, except for flags, which must be either 0 (which 798 "aio_msync", above, except for flags, which must be either 0 (which
664 reads all pages and ensures they are instantiated) or 799 reads all pages and ensures they are instantiated) or
665 "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading 800 "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading
666 and writing an octet from it, which dirties the page). 801 and writing an octet from it, which dirties the page).
802
803 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
804 This is a rather advanced IO::AIO call, which works best on
805 mmap(2)ed scalars.
806
807 It reads in all the pages of the underlying storage into memory (if
808 any) and locks them, so they are not getting swapped/paged out or
809 removed.
810
811 If $length is undefined, then the scalar will be locked till the
812 end.
813
814 On systems that do not implement "mlock", this function returns -1
815 and sets errno to "ENOSYS".
816
817 Note that the corresponding "munlock" is synchronous and is
818 documented under "MISCELLANEOUS FUNCTIONS".
819
820 Example: open a file, mmap and mlock it - both will be undone when
821 $data gets destroyed.
822
823 open my $fh, "<", $path or die "$path: $!";
824 my $data;
825 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
826 aio_mlock $data; # mlock in background
827
828 aio_mlockall $flags, $callback->($status)
829 Calls the "mlockall" function with the given $flags (a combination
830 of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
831
832 On systems that do not implement "mlockall", this function returns
833 -1 and sets errno to "ENOSYS".
834
835 Note that the corresponding "munlockall" is synchronous and is
836 documented under "MISCELLANEOUS FUNCTIONS".
837
838 Example: asynchronously lock all current and future pages into
839 memory.
840
841 aio_mlockall IO::AIO::MCL_FUTURE;
667 842
668 aio_group $callback->(...) 843 aio_group $callback->(...)
669 This is a very special aio request: Instead of doing something, it 844 This is a very special aio request: Instead of doing something, it
670 is a container for other aio requests, which is useful if you want 845 is a container for other aio requests, which is useful if you want
671 to bundle many requests into a single, composite, request with a 846 to bundle many requests into a single, composite, request with a
… …
867 1042
868 See "poll_cb" for an example. 1043 See "poll_cb" for an example.
869 1044
870 IO::AIO::poll_cb 1045 IO::AIO::poll_cb
871 Process some outstanding events on the result pipe. You have to call 1046 Process some outstanding events on the result pipe. You have to call
872 this regularly. Returns 0 if all events could be processed, or -1 if 1047 this regularly. Returns 0 if all events could be processed (or there
873 it returned earlier for whatever reason. Returns immediately when no 1048 were no events to process), or -1 if it returned earlier for
874 events are outstanding. The amount of events processed depends on 1049 whatever reason. Returns immediately when no events are outstanding.
875 the settings of "IO::AIO::max_poll_req" and 1050 The amount of events processed depends on the settings of
876 "IO::AIO::max_poll_time". 1051 "IO::AIO::max_poll_req" and "IO::AIO::max_poll_time".
877 1052
878 If not all requests were processed for whatever reason, the 1053 If not all requests were processed for whatever reason, the
879 filehandle will still be ready when "poll_cb" returns, so normally 1054 filehandle will still be ready when "poll_cb" returns, so normally
880 you don't have to do anything special to have it called later. 1055 you don't have to do anything special to have it called later.
881 1056
1057 Apart from calling "IO::AIO::poll_cb" when the event filehandle
1058 becomes ready, it can be beneficial to call this function from loops
1059 which submit a lot of requests, to make sure the results get
1060 processed when they become available and not just when the loop is
1061 finished and the event loop takes over again. This function returns
1062 very fast when there are no outstanding requests.
1063
882 Example: Install an Event watcher that automatically calls 1064 Example: Install an Event watcher that automatically calls
883 IO::AIO::poll_cb with high priority (more examples can be found in 1065 IO::AIO::poll_cb with high priority (more examples can be found in
884 the SYNOPSIS section, at the top of this document): 1066 the SYNOPSIS section, at the top of this document):
885 1067
886 Event->io (fd => IO::AIO::poll_fileno, 1068 Event->io (fd => IO::AIO::poll_fileno,
887 poll => 'r', async => 1, 1069 poll => 'r', async => 1,
888 cb => \&IO::AIO::poll_cb); 1070 cb => \&IO::AIO::poll_cb);
1071
1072 IO::AIO::poll_wait
1073 If there are any outstanding requests and none of them in the result
1074 phase, wait till the result filehandle becomes ready for reading
1075 (simply does a "select" on the filehandle. This is useful if you
1076 want to synchronously wait for some requests to finish).
1077
1078 See "nreqs" for an example.
1079
1080 IO::AIO::poll
1081 Waits until some requests have been handled.
1082
1083 Returns the number of requests processed, but is otherwise strictly
1084 equivalent to:
1085
1086 IO::AIO::poll_wait, IO::AIO::poll_cb
1087
1088 IO::AIO::flush
1089 Wait till all outstanding AIO requests have been handled.
1090
1091 Strictly equivalent to:
1092
1093 IO::AIO::poll_wait, IO::AIO::poll_cb
1094 while IO::AIO::nreqs;
889 1095
890 IO::AIO::max_poll_reqs $nreqs 1096 IO::AIO::max_poll_reqs $nreqs
891 IO::AIO::max_poll_time $seconds 1097 IO::AIO::max_poll_time $seconds
892 These set the maximum number of requests (default 0, meaning 1098 These set the maximum number of requests (default 0, meaning
893 infinity) that are being processed by "IO::AIO::poll_cb" in one 1099 infinity) that are being processed by "IO::AIO::poll_cb" in one
… …
917 # use a low priority so other tasks have priority 1123 # use a low priority so other tasks have priority
918 Event->io (fd => IO::AIO::poll_fileno, 1124 Event->io (fd => IO::AIO::poll_fileno,
919 poll => 'r', nice => 1, 1125 poll => 'r', nice => 1,
920 cb => &IO::AIO::poll_cb); 1126 cb => &IO::AIO::poll_cb);
921 1127
922 IO::AIO::poll_wait
923 If there are any outstanding requests and none of them in the result
924 phase, wait till the result filehandle becomes ready for reading
925 (simply does a "select" on the filehandle. This is useful if you
926 want to synchronously wait for some requests to finish).
927
928 See "nreqs" for an example.
929
930 IO::AIO::poll
931 Waits until some requests have been handled.
932
933 Returns the number of requests processed, but is otherwise strictly
934 equivalent to:
935
936 IO::AIO::poll_wait, IO::AIO::poll_cb
937
938 IO::AIO::flush
939 Wait till all outstanding AIO requests have been handled.
940
941 Strictly equivalent to:
942
943 IO::AIO::poll_wait, IO::AIO::poll_cb
944 while IO::AIO::nreqs;
945
946 CONTROLLING THE NUMBER OF THREADS 1128 CONTROLLING THE NUMBER OF THREADS
947 IO::AIO::min_parallel $nthreads 1129 IO::AIO::min_parallel $nthreads
948 Set the minimum number of AIO threads to $nthreads. The current 1130 Set the minimum number of AIO threads to $nthreads. The current
949 default is 8, which means eight asynchronous operations can execute 1131 default is 8, which means eight asynchronous operations can execute
950 concurrently at any one time (the number of outstanding requests, 1132 concurrently at any one time (the number of outstanding requests,
… …
979 1161
980 Under normal circumstances you don't need to call this function. 1162 Under normal circumstances you don't need to call this function.
981 1163
982 IO::AIO::max_idle $nthreads 1164 IO::AIO::max_idle $nthreads
983 Limit the number of threads (default: 4) that are allowed to idle 1165 Limit the number of threads (default: 4) that are allowed to idle
984 (i.e., threads that did not get a request to process within 10 1166 (i.e., threads that did not get a request to process within the idle
985 seconds). That means if a thread becomes idle while $nthreads other 1167 timeout (default: 10 seconds). That means if a thread becomes idle
986 threads are also idle, it will free its resources and exit. 1168 while $nthreads other threads are also idle, it will free its
1169 resources and exit.
987 1170
988 This is useful when you allow a large number of threads (e.g. 100 or 1171 This is useful when you allow a large number of threads (e.g. 100 or
989 1000) to allow for extremely high load situations, but want to free 1172 1000) to allow for extremely high load situations, but want to free
990 resources under normal circumstances (1000 threads can easily 1173 resources under normal circumstances (1000 threads can easily
991 consume 30MB of RAM). 1174 consume 30MB of RAM).
992 1175
993 The default is probably ok in most situations, especially if thread 1176 The default is probably ok in most situations, especially if thread
994 creation is fast. If thread creation is very slow on your system you 1177 creation is fast. If thread creation is very slow on your system you
995 might want to use larger values. 1178 might want to use larger values.
996 1179
1180 IO::AIO::idle_timeout $seconds
1181 Sets the minimum idle timeout (default 10) after which worker
1182 threads are allowed to exit. SEe "IO::AIO::max_idle".
1183
997 IO::AIO::max_outstanding $maxreqs 1184 IO::AIO::max_outstanding $maxreqs
1185 Sets the maximum number of outstanding requests to $nreqs. If you do
1186 queue up more than this number of requests, the next call to
1187 "IO::AIO::poll_cb" (and other functions calling "poll_cb", such as
1188 "IO::AIO::flush" or "IO::AIO::poll") will block until the limit is
1189 no longer exceeded.
1190
1191 In other words, this setting does not enforce a queue limit, but can
1192 be used to make poll functions block if the limit is exceeded.
1193
998 This is a very bad function to use in interactive programs because 1194 This is a very bad function to use in interactive programs because
999 it blocks, and a bad way to reduce concurrency because it is 1195 it blocks, and a bad way to reduce concurrency because it is
1000 inexact: Better use an "aio_group" together with a feed callback. 1196 inexact: Better use an "aio_group" together with a feed callback.
1001 1197
1002 Sets the maximum number of outstanding requests to $nreqs. If you do 1198 It's main use is in scripts without an event loop - when you want to
1003 queue up more than this number of requests, the next call to the 1199 stat a lot of files, you can write somehting like this:
1004 "poll_cb" (and "poll_some" and other functions calling "poll_cb")
1005 function will block until the limit is no longer exceeded.
1006 1200
1007 The default value is very large, so there is no practical limit on 1201 IO::AIO::max_outstanding 32;
1202
1203 for my $path (...) {
1204 aio_stat $path , ...;
1205 IO::AIO::poll_cb;
1206 }
1207
1208 IO::AIO::flush;
1209
1210 The call to "poll_cb" inside the loop will normally return
1211 instantly, but as soon as more thna 32 reqeusts are in-flight, it
1212 will block until some requests have been handled. This keeps the
1213 loop from pushing a large number of "aio_stat" requests onto the
1214 queue.
1215
1216 The default value for "max_outstanding" is very large, so there is
1008 the number of outstanding requests. 1217 no practical limit on the number of outstanding requests.
1009
1010 You can still queue as many requests as you want. Therefore,
1011 "max_outstanding" is mainly useful in simple scripts (with low
1012 values) or as a stop gap to shield against fatal memory overflow
1013 (with large values).
1014 1218
1015 STATISTICAL INFORMATION 1219 STATISTICAL INFORMATION
1016 IO::AIO::nreqs 1220 IO::AIO::nreqs
1017 Returns the number of requests currently in the ready, execute or 1221 Returns the number of requests currently in the ready, execute or
1018 pending states (i.e. for which their callback has not been invoked 1222 pending states (i.e. for which their callback has not been invoked
… …
1042 set to non-blocking operations). 1246 set to non-blocking operations).
1043 1247
1044 Returns the number of bytes copied, or -1 on error. 1248 Returns the number of bytes copied, or -1 on error.
1045 1249
1046 IO::AIO::fadvise $fh, $offset, $len, $advice 1250 IO::AIO::fadvise $fh, $offset, $len, $advice
1047 Simply calls the "posix_fadvise" function (see it's manpage for 1251 Simply calls the "posix_fadvise" function (see its manpage for
1048 details). The following advice constants are avaiable: 1252 details). The following advice constants are avaiable:
1049 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL", 1253 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1050 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE", 1254 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1051 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED". 1255 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1052 1256
1053 On systems that do not implement "posix_fadvise", this function 1257 On systems that do not implement "posix_fadvise", this function
1054 returns ENOSYS, otherwise the return value of "posix_fadvise". 1258 returns ENOSYS, otherwise the return value of "posix_fadvise".
1055 1259
1260 IO::AIO::madvise $scalar, $offset, $len, $advice
1261 Simply calls the "posix_madvise" function (see its manpage for
1262 details). The following advice constants are avaiable:
1263 "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1264 "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1265 "IO::AIO::MADV_DONTNEED".
1266
1267 On systems that do not implement "posix_madvise", this function
1268 returns ENOSYS, otherwise the return value of "posix_madvise".
1269
1270 IO::AIO::mprotect $scalar, $offset, $len, $protect
1271 Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1272 $scalar (see its manpage for details). The following protect
1273 constants are avaiable: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
1274 "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1275
1276 On systems that do not implement "mprotect", this function returns
1277 ENOSYS, otherwise the return value of "mprotect".
1278
1279 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1280 Memory-maps a file (or anonymous memory range) and attaches it to
1281 the given $scalar, which will act like a string scalar.
1282
1283 The only operations allowed on the scalar are "substr"/"vec" that
1284 don't change the string length, and most read-only operations such
1285 as copying it or searching it with regexes and so on.
1286
1287 Anything else is unsafe and will, at best, result in memory leaks.
1288
1289 The memory map associated with the $scalar is automatically removed
1290 when the $scalar is destroyed, or when the "IO::AIO::mmap" or
1291 "IO::AIO::munmap" functions are called.
1292
1293 This calls the "mmap"(2) function internally. See your system's
1294 manual page for details on the $length, $prot and $flags parameters.
1295
1296 The $length must be larger than zero and smaller than the actual
1297 filesize.
1298
1299 $prot is a combination of "IO::AIO::PROT_NONE",
1300 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1301 "IO::AIO::PROT_WRITE",
1302
1303 $flags can be a combination of "IO::AIO::MAP_SHARED" or
1304 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1305 not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS"
1306 (which is set to "MAP_ANON" if your system only provides this
1307 constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
1308 "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or
1309 "IO::AIO::MAP_NONBLOCK"
1310
1311 If $fh is "undef", then a file descriptor of -1 is passed.
1312
1313 $offset is the offset from the start of the file - it generally must
1314 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
1315
1316 Example:
1317
1318 use Digest::MD5;
1319 use IO::AIO;
1320
1321 open my $fh, "<verybigfile"
1322 or die "$!";
1323
1324 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
1325 or die "verybigfile: $!";
1326
1327 my $fast_md5 = md5 $data;
1328
1329 IO::AIO::munmap $scalar
1330 Removes a previous mmap and undefines the $scalar.
1331
1332 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1333 Calls the "munlock" function, undoing the effects of a previous
1334 "aio_mlock" call (see its description for details).
1335
1336 IO::AIO::munlockall
1337 Calls the "munlockall" function.
1338
1339 On systems that do not implement "munlockall", this function returns
1340 ENOSYS, otherwise the return value of "munlockall".
1341
1342EVENT LOOP INTEGRATION
1343 It is recommended to use AnyEvent::AIO to integrate IO::AIO
1344 automatically into many event loops:
1345
1346 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
1347 use AnyEvent::AIO;
1348
1349 You can also integrate IO::AIO manually into many event loops, here are
1350 some examples of how to do this:
1351
1352 # EV integration
1353 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
1354
1355 # Event integration
1356 Event->io (fd => IO::AIO::poll_fileno,
1357 poll => 'r',
1358 cb => \&IO::AIO::poll_cb);
1359
1360 # Glib/Gtk2 integration
1361 add_watch Glib::IO IO::AIO::poll_fileno,
1362 in => sub { IO::AIO::poll_cb; 1 };
1363
1364 # Tk integration
1365 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
1366 readable => \&IO::AIO::poll_cb);
1367
1368 # Danga::Socket integration
1369 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
1370 \&IO::AIO::poll_cb);
1371
1056 FORK BEHAVIOUR 1372 FORK BEHAVIOUR
1057 This module should do "the right thing" when the process using it forks: 1373 Usage of pthreads in a program changes the semantics of fork
1374 considerably. Specifically, only async-safe functions can be called
1375 after fork. Perl doesn't know about this, so in general, you cannot call
1376 fork with defined behaviour in perl. IO::AIO uses pthreads, so this
1377 applies, but many other extensions and (for inexplicable reasons) perl
1378 itself often is linked against pthreads, so this limitation applies.
1058 1379
1059 Before the fork, IO::AIO enters a quiescent state where no requests can 1380 Some operating systems have extensions that allow safe use of fork, and
1060 be added in other threads and no results will be processed. After the 1381 this module should do "the right thing" on those, and tries on others.
1061 fork the parent simply leaves the quiescent state and continues 1382 At the time of this writing (2011) only GNU/Linux supports these
1062 request/result processing, while the child frees the request/result 1383 extensions to POSIX.
1063 queue (so that the requests started before the fork will only be handled
1064 in the parent). Threads will be started on demand until the limit set in
1065 the parent process has been reached again.
1066
1067 In short: the parent will, after a short pause, continue as if fork had
1068 not been called, while the child will act as if IO::AIO has not been
1069 used yet.
1070 1384
1071 MEMORY USAGE 1385 MEMORY USAGE
1072 Per-request usage: 1386 Per-request usage:
1073 1387
1074 Each aio request uses - depending on your architecture - around 100-200 1388 Each aio request uses - depending on your architecture - around 100-200

Diff Legend

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