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

Comparing IO-AIO/README (file contents):
Revision 1.42 by root, Thu Jan 7 20:25:57 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
… …
355 433
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.
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".
360 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: $!";
… …
453 540
454 The only (POSIX-) portable way of calling this function is: 541 The only (POSIX-) portable way of calling this function is:
455 542
456 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 543 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
457 544
545 See "aio_stat" for info about some potentially helpful extra
546 constants and functions.
547
458 aio_link $srcpath, $dstpath, $callback->($status) 548 aio_link $srcpath, $dstpath, $callback->($status)
459 Asynchronously create a new link to the existing object at $srcpath 549 Asynchronously create a new link to the existing object at $srcpath
460 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.
461 551
462 aio_symlink $srcpath, $dstpath, $callback->($status) 552 aio_symlink $srcpath, $dstpath, $callback->($status)
… …
498 The flags are a combination of the following constants, ORed 588 The flags are a combination of the following constants, ORed
499 together (the flags will also be passed to the callback, possibly 589 together (the flags will also be passed to the callback, possibly
500 modified): 590 modified):
501 591
502 IO::AIO::READDIR_DENTS 592 IO::AIO::READDIR_DENTS
503 When this flag is off, then the callback gets an arrayref with 593 When this flag is off, then the callback gets an arrayref
504 of names only (as with "aio_readdir"), otherwise it gets an 594 consisting of names only (as with "aio_readdir"), otherwise it
505 arrayref with "[$name, $type, $inode]" arrayrefs, each 595 gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
506 describing a single directory entry in more detail. 596 describing a single directory entry in more detail.
507 597
508 $name is the name of the entry. 598 $name is the name of the entry.
509 599
510 $type is one of the "IO::AIO::DT_xxx" constants: 600 $type is one of the "IO::AIO::DT_xxx" constants:
… …
523 unspecified content on systems that do not deliver the inode 613 unspecified content on systems that do not deliver the inode
524 information. 614 information.
525 615
526 IO::AIO::READDIR_DIRS_FIRST 616 IO::AIO::READDIR_DIRS_FIRST
527 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
528 order where likely directories come first. This is useful when 618 order where likely directories come first, in optimal stat
529 you need to quickly find directories, or you want to find all 619 order. This is useful when you need to quickly find directories,
530 directories while avoiding to stat() each entry. 620 or you want to find all directories while avoiding to stat()
621 each entry.
531 622
532 If the system returns type information in readdir, then this is 623 If the system returns type information in readdir, then this is
533 used to find directories directly. Otherwise, likely directories 624 used to find directories directly. Otherwise, likely directories
534 are files beginning with ".", or otherwise files with no dots, 625 are names beginning with ".", or otherwise names with no dots,
535 of which files with short names are tried first. 626 of which names with short names are tried first.
536 627
537 IO::AIO::READDIR_STAT_ORDER 628 IO::AIO::READDIR_STAT_ORDER
538 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
539 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
540 to stat() all files in the given directory, then the returned 631 to stat() all files in the given directory, then the returned
… …
683 Passes 0 when everything went ok, and -1 on error. 774 Passes 0 when everything went ok, and -1 on error.
684 775
685 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, 776 aio_msync $scalar, $offset = 0, $length = undef, flags = 0,
686 $callback->($status) 777 $callback->($status)
687 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
688 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,
689 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
690 aio operation is pending on it). 782 operation is pending on it).
691 783
692 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
693 memory area starting at $offset in the string and ending $length 785 memory area starting at $offset in the string and ending $length
694 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
695 $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
… …
705 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
706 "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
707 reads all pages and ensures they are instantiated) or 799 reads all pages and ensures they are instantiated) or
708 "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
709 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;
710 842
711 aio_group $callback->(...) 843 aio_group $callback->(...)
712 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
713 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
714 to bundle many requests into a single, composite, request with a 846 to bundle many requests into a single, composite, request with a
… …
910 1042
911 See "poll_cb" for an example. 1043 See "poll_cb" for an example.
912 1044
913 IO::AIO::poll_cb 1045 IO::AIO::poll_cb
914 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
915 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
916 it returned earlier for whatever reason. Returns immediately when no 1048 were no events to process), or -1 if it returned earlier for
917 events are outstanding. The amount of events processed depends on 1049 whatever reason. Returns immediately when no events are outstanding.
918 the settings of "IO::AIO::max_poll_req" and 1050 The amount of events processed depends on the settings of
919 "IO::AIO::max_poll_time". 1051 "IO::AIO::max_poll_req" and "IO::AIO::max_poll_time".
920 1052
921 If not all requests were processed for whatever reason, the 1053 If not all requests were processed for whatever reason, the
922 filehandle will still be ready when "poll_cb" returns, so normally 1054 filehandle will still be ready when "poll_cb" returns, so normally
923 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.
924 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
925 Example: Install an Event watcher that automatically calls 1064 Example: Install an Event watcher that automatically calls
926 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
927 the SYNOPSIS section, at the top of this document): 1066 the SYNOPSIS section, at the top of this document):
928 1067
929 Event->io (fd => IO::AIO::poll_fileno, 1068 Event->io (fd => IO::AIO::poll_fileno,
930 poll => 'r', async => 1, 1069 poll => 'r', async => 1,
931 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;
932 1095
933 IO::AIO::max_poll_reqs $nreqs 1096 IO::AIO::max_poll_reqs $nreqs
934 IO::AIO::max_poll_time $seconds 1097 IO::AIO::max_poll_time $seconds
935 These set the maximum number of requests (default 0, meaning 1098 These set the maximum number of requests (default 0, meaning
936 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
… …
960 # use a low priority so other tasks have priority 1123 # use a low priority so other tasks have priority
961 Event->io (fd => IO::AIO::poll_fileno, 1124 Event->io (fd => IO::AIO::poll_fileno,
962 poll => 'r', nice => 1, 1125 poll => 'r', nice => 1,
963 cb => &IO::AIO::poll_cb); 1126 cb => &IO::AIO::poll_cb);
964 1127
965 IO::AIO::poll_wait
966 If there are any outstanding requests and none of them in the result
967 phase, wait till the result filehandle becomes ready for reading
968 (simply does a "select" on the filehandle. This is useful if you
969 want to synchronously wait for some requests to finish).
970
971 See "nreqs" for an example.
972
973 IO::AIO::poll
974 Waits until some requests have been handled.
975
976 Returns the number of requests processed, but is otherwise strictly
977 equivalent to:
978
979 IO::AIO::poll_wait, IO::AIO::poll_cb
980
981 IO::AIO::flush
982 Wait till all outstanding AIO requests have been handled.
983
984 Strictly equivalent to:
985
986 IO::AIO::poll_wait, IO::AIO::poll_cb
987 while IO::AIO::nreqs;
988
989 CONTROLLING THE NUMBER OF THREADS 1128 CONTROLLING THE NUMBER OF THREADS
990 IO::AIO::min_parallel $nthreads 1129 IO::AIO::min_parallel $nthreads
991 Set the minimum number of AIO threads to $nthreads. The current 1130 Set the minimum number of AIO threads to $nthreads. The current
992 default is 8, which means eight asynchronous operations can execute 1131 default is 8, which means eight asynchronous operations can execute
993 concurrently at any one time (the number of outstanding requests, 1132 concurrently at any one time (the number of outstanding requests,
… …
1022 1161
1023 Under normal circumstances you don't need to call this function. 1162 Under normal circumstances you don't need to call this function.
1024 1163
1025 IO::AIO::max_idle $nthreads 1164 IO::AIO::max_idle $nthreads
1026 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
1027 (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
1028 seconds). That means if a thread becomes idle while $nthreads other 1167 timeout (default: 10 seconds). That means if a thread becomes idle
1029 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.
1030 1170
1031 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
1032 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
1033 resources under normal circumstances (1000 threads can easily 1173 resources under normal circumstances (1000 threads can easily
1034 consume 30MB of RAM). 1174 consume 30MB of RAM).
1035 1175
1036 The default is probably ok in most situations, especially if thread 1176 The default is probably ok in most situations, especially if thread
1037 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
1038 might want to use larger values. 1178 might want to use larger values.
1039 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
1040 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
1041 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
1042 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
1043 inexact: Better use an "aio_group" together with a feed callback. 1196 inexact: Better use an "aio_group" together with a feed callback.
1044 1197
1045 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
1046 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:
1047 "poll_cb" (and "poll_some" and other functions calling "poll_cb")
1048 function will block until the limit is no longer exceeded.
1049 1200
1050 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
1051 the number of outstanding requests. 1217 no practical limit on the number of outstanding requests.
1052
1053 You can still queue as many requests as you want. Therefore,
1054 "max_outstanding" is mainly useful in simple scripts (with low
1055 values) or as a stop gap to shield against fatal memory overflow
1056 (with large values).
1057 1218
1058 STATISTICAL INFORMATION 1219 STATISTICAL INFORMATION
1059 IO::AIO::nreqs 1220 IO::AIO::nreqs
1060 Returns the number of requests currently in the ready, execute or 1221 Returns the number of requests currently in the ready, execute or
1061 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
… …
1085 set to non-blocking operations). 1246 set to non-blocking operations).
1086 1247
1087 Returns the number of bytes copied, or -1 on error. 1248 Returns the number of bytes copied, or -1 on error.
1088 1249
1089 IO::AIO::fadvise $fh, $offset, $len, $advice 1250 IO::AIO::fadvise $fh, $offset, $len, $advice
1090 Simply calls the "posix_fadvise" function (see it's manpage for 1251 Simply calls the "posix_fadvise" function (see its manpage for
1091 details). The following advice constants are avaiable: 1252 details). The following advice constants are avaiable:
1092 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL", 1253 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1093 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE", 1254 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1094 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED". 1255 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1095 1256
1096 On systems that do not implement "posix_fadvise", this function 1257 On systems that do not implement "posix_fadvise", this function
1097 returns ENOSYS, otherwise the return value of "posix_fadvise". 1258 returns ENOSYS, otherwise the return value of "posix_fadvise".
1098 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
1099 FORK BEHAVIOUR 1372 FORK BEHAVIOUR
1100 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.
1101 1379
1102 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
1103 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.
1104 fork the parent simply leaves the quiescent state and continues 1382 At the time of this writing (2011) only GNU/Linux supports these
1105 request/result processing, while the child frees the request/result 1383 extensions to POSIX.
1106 queue (so that the requests started before the fork will only be handled
1107 in the parent). Threads will be started on demand until the limit set in
1108 the parent process has been reached again.
1109
1110 In short: the parent will, after a short pause, continue as if fork had
1111 not been called, while the child will act as if IO::AIO has not been
1112 used yet.
1113 1384
1114 MEMORY USAGE 1385 MEMORY USAGE
1115 Per-request usage: 1386 Per-request usage:
1116 1387
1117 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