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.44 by root, Mon Nov 1 22:03:43 2010 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::max_outstanding $maxreqs
210 IO::AIO::nreqs
211 IO::AIO::nready
212 IO::AIO::npending
213
214 IO::AIO::sendfile $ofh, $ifh, $offset, $count
215 IO::AIO::fadvise $fh, $offset, $len, $advice
216 IO::AIO::madvise $scalar, $offset, $length, $advice
217 IO::AIO::mprotect $scalar, $offset, $length, $protect
218 IO::AIO::munlock $scalar, $offset = 0, $length = undef
219 IO::AIO::munlockall
220
173 AIO REQUEST FUNCTIONS 221 AIO REQUEST FUNCTIONS
174 All the "aio_*" calls are more or less thin wrappers around the syscall 222 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 223 with the same name (sans "aio_"). The arguments are similar or
176 identical, and they all accept an additional (and optional) $callback 224 identical, and they all accept an additional (and optional) $callback
177 argument which must be a code reference. This code reference will get 225 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 296 will be modified by the umask in effect then the request is being
249 executed, so better never change the umask. 297 executed, so better never change the umask.
250 298
251 Example: 299 Example:
252 300
253 aio_open "/etc/passwd", O_RDONLY, 0, sub { 301 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
254 if ($_[0]) { 302 if ($_[0]) {
255 print "open successful, fh is $_[0]\n"; 303 print "open successful, fh is $_[0]\n";
256 ... 304 ...
257 } else { 305 } else {
258 die "open failed: $!\n"; 306 die "open failed: $!\n";
313 more than one "aio_sendfile" per $out_fh, as they will interfere 361 more than one "aio_sendfile" per $out_fh, as they will interfere
314 with each other. 362 with each other.
315 363
316 This call tries to make use of a native "sendfile" syscall to 364 This call tries to make use of a native "sendfile" syscall to
317 provide zero-copy operation. For this to work, $out_fh should refer 365 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. 366 to a socket, and $in_fh should refer to an mmap'able file.
319 367
320 If a native sendfile cannot be found or it fails with "ENOSYS", 368 If a native sendfile cannot be found or it fails with "ENOSYS",
321 "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK", 369 "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK",
322 it will be emulated, so you can call "aio_sendfile" on any type of 370 it will be emulated, so you can call "aio_sendfile" on any type of
323 filehandle regardless of the limitations of the operating system. 371 filehandle regardless of the limitations of the operating system.
683 Passes 0 when everything went ok, and -1 on error. 731 Passes 0 when everything went ok, and -1 on error.
684 732
685 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, 733 aio_msync $scalar, $offset = 0, $length = undef, flags = 0,
686 $callback->($status) 734 $callback->($status)
687 This is a rather advanced IO::AIO call, which only works on 735 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 736 mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
737 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 738 note that the scalar must only be modified in-place while an aio
690 aio operation is pending on it). 739 operation is pending on it).
691 740
692 It calls the "msync" function of your OS, if available, with the 741 It calls the "msync" function of your OS, if available, with the
693 memory area starting at $offset in the string and ending $length 742 memory area starting at $offset in the string and ending $length
694 bytes later. If $length is negative, counts from the end, and if 743 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 744 $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 754 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 755 "aio_msync", above, except for flags, which must be either 0 (which
707 reads all pages and ensures they are instantiated) or 756 reads all pages and ensures they are instantiated) or
708 "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading 757 "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading
709 and writing an octet from it, which dirties the page). 758 and writing an octet from it, which dirties the page).
759
760 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
761 This is a rather advanced IO::AIO call, which works best on
762 mmap(2)ed scalars.
763
764 It reads in all the pages of the underlying storage into memory (if
765 any) and locks them, so they are not getting swapped/paged out or
766 removed.
767
768 If $length is undefined, then the scalar will be locked till the
769 end.
770
771 On systems that do not implement "mlock", this function returns -1
772 and sets errno to "ENOSYS".
773
774 Note that the corresponding "munlock" is synchronous and is
775 documented under "MISCELLANEOUS FUNCTIONS".
776
777 Example: open a file, mmap and mlock it - both will be undone when
778 $data gets destroyed.
779
780 open my $fh, "<", $path or die "$path: $!";
781 my $data;
782 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
783 aio_mlock $data; # mlock in background
784
785 aio_mlockall $flags, $callback->($status)
786 Calls the "mlockall" function with the given $flags (a combination
787 of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
788
789 On systems that do not implement "mlockall", this function returns
790 -1 and sets errno to "ENOSYS".
791
792 Note that the corresponding "munlockall" is synchronous and is
793 documented under "MISCELLANEOUS FUNCTIONS".
794
795 Example: asynchronously lock all current and future pages into
796 memory.
797
798 aio_mlockall IO::AIO::MCL_FUTURE;
710 799
711 aio_group $callback->(...) 800 aio_group $callback->(...)
712 This is a very special aio request: Instead of doing something, it 801 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 802 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 803 to bundle many requests into a single, composite, request with a
928 1017
929 Event->io (fd => IO::AIO::poll_fileno, 1018 Event->io (fd => IO::AIO::poll_fileno,
930 poll => 'r', async => 1, 1019 poll => 'r', async => 1,
931 cb => \&IO::AIO::poll_cb); 1020 cb => \&IO::AIO::poll_cb);
932 1021
1022 IO::AIO::poll_wait
1023 If there are any outstanding requests and none of them in the result
1024 phase, wait till the result filehandle becomes ready for reading
1025 (simply does a "select" on the filehandle. This is useful if you
1026 want to synchronously wait for some requests to finish).
1027
1028 See "nreqs" for an example.
1029
1030 IO::AIO::poll
1031 Waits until some requests have been handled.
1032
1033 Returns the number of requests processed, but is otherwise strictly
1034 equivalent to:
1035
1036 IO::AIO::poll_wait, IO::AIO::poll_cb
1037
1038 IO::AIO::flush
1039 Wait till all outstanding AIO requests have been handled.
1040
1041 Strictly equivalent to:
1042
1043 IO::AIO::poll_wait, IO::AIO::poll_cb
1044 while IO::AIO::nreqs;
1045
933 IO::AIO::max_poll_reqs $nreqs 1046 IO::AIO::max_poll_reqs $nreqs
934 IO::AIO::max_poll_time $seconds 1047 IO::AIO::max_poll_time $seconds
935 These set the maximum number of requests (default 0, meaning 1048 These set the maximum number of requests (default 0, meaning
936 infinity) that are being processed by "IO::AIO::poll_cb" in one 1049 infinity) that are being processed by "IO::AIO::poll_cb" in one
937 call, respectively the maximum amount of time (default 0, meaning 1050 call, respectively the maximum amount of time (default 0, meaning
960 # use a low priority so other tasks have priority 1073 # use a low priority so other tasks have priority
961 Event->io (fd => IO::AIO::poll_fileno, 1074 Event->io (fd => IO::AIO::poll_fileno,
962 poll => 'r', nice => 1, 1075 poll => 'r', nice => 1,
963 cb => &IO::AIO::poll_cb); 1076 cb => &IO::AIO::poll_cb);
964 1077
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 1078 CONTROLLING THE NUMBER OF THREADS
990 IO::AIO::min_parallel $nthreads 1079 IO::AIO::min_parallel $nthreads
991 Set the minimum number of AIO threads to $nthreads. The current 1080 Set the minimum number of AIO threads to $nthreads. The current
992 default is 8, which means eight asynchronous operations can execute 1081 default is 8, which means eight asynchronous operations can execute
993 concurrently at any one time (the number of outstanding requests, 1082 concurrently at any one time (the number of outstanding requests,
1085 set to non-blocking operations). 1174 set to non-blocking operations).
1086 1175
1087 Returns the number of bytes copied, or -1 on error. 1176 Returns the number of bytes copied, or -1 on error.
1088 1177
1089 IO::AIO::fadvise $fh, $offset, $len, $advice 1178 IO::AIO::fadvise $fh, $offset, $len, $advice
1090 Simply calls the "posix_fadvise" function (see it's manpage for 1179 Simply calls the "posix_fadvise" function (see its manpage for
1091 details). The following advice constants are avaiable: 1180 details). The following advice constants are avaiable:
1092 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL", 1181 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1093 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE", 1182 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1094 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED". 1183 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1095 1184
1096 On systems that do not implement "posix_fadvise", this function 1185 On systems that do not implement "posix_fadvise", this function
1097 returns ENOSYS, otherwise the return value of "posix_fadvise". 1186 returns ENOSYS, otherwise the return value of "posix_fadvise".
1187
1188 IO::AIO::madvise $scalar, $offset, $len, $advice
1189 Simply calls the "posix_madvise" function (see its manpage for
1190 details). The following advice constants are avaiable:
1191 "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1192 "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1193 "IO::AIO::MADV_DONTNEED".
1194
1195 On systems that do not implement "posix_madvise", this function
1196 returns ENOSYS, otherwise the return value of "posix_madvise".
1197
1198 IO::AIO::mprotect $scalar, $offset, $len, $protect
1199 Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1200 $scalar (see its manpage for details). The following protect
1201 constants are avaiable: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
1202 "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1203
1204 On systems that do not implement "mprotect", this function returns
1205 ENOSYS, otherwise the return value of "mprotect".
1206
1207 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1208 Memory-maps a file (or anonymous memory range) and attaches it to
1209 the given $scalar, which will act like a string scalar.
1210
1211 The only operations allowed on the scalar are "substr"/"vec" that
1212 don't change the string length, and most read-only operations such
1213 as copying it or searching it with regexes and so on.
1214
1215 Anything else is unsafe and will, at best, result in memory leaks.
1216
1217 The memory map associated with the $scalar is automatically removed
1218 when the $scalar is destroyed, or when the "IO::AIO::mmap" or
1219 "IO::AIO::munmap" functions are called.
1220
1221 This calls the "mmap"(2) function internally. See your system's
1222 manual page for details on the $length, $prot and $flags parameters.
1223
1224 The $length must be larger than zero and smaller than the actual
1225 filesize.
1226
1227 $prot is a combination of "IO::AIO::PROT_NONE",
1228 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1229 "IO::AIO::PROT_WRITE",
1230
1231 $flags can be a combination of "IO::AIO::MAP_SHARED" or
1232 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1233 not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS"
1234 (which is set to "MAP_ANON" if your system only provides this
1235 constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
1236 "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or
1237 "IO::AIO::MAP_NONBLOCK"
1238
1239 If $fh is "undef", then a file descriptor of -1 is passed.
1240
1241 $offset is the offset from the start of the file - it generally must
1242 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
1243
1244 Example:
1245
1246 use Digest::MD5;
1247 use IO::AIO;
1248
1249 open my $fh, "<verybigfile"
1250 or die "$!";
1251
1252 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
1253 or die "verybigfile: $!";
1254
1255 my $fast_md5 = md5 $data;
1256
1257 IO::AIO::munmap $scalar
1258 Removes a previous mmap and undefines the $scalar.
1259
1260 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1261 Calls the "munlock" function, undoing the effects of a previous
1262 "aio_mlock" call (see its description for details).
1263
1264 IO::AIO::munlockall
1265 Calls the "munlockall" function.
1266
1267 On systems that do not implement "munlockall", this function returns
1268 ENOSYS, otherwise the return value of "munlockall".
1269
1270EVENT LOOP INTEGRATION
1271 It is recommended to use AnyEvent::AIO to integrate IO::AIO
1272 automatically into many event loops:
1273
1274 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
1275 use AnyEvent::AIO;
1276
1277 You can also integrate IO::AIO manually into many event loops, here are
1278 some examples of how to do this:
1279
1280 # EV integration
1281 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
1282
1283 # Event integration
1284 Event->io (fd => IO::AIO::poll_fileno,
1285 poll => 'r',
1286 cb => \&IO::AIO::poll_cb);
1287
1288 # Glib/Gtk2 integration
1289 add_watch Glib::IO IO::AIO::poll_fileno,
1290 in => sub { IO::AIO::poll_cb; 1 };
1291
1292 # Tk integration
1293 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
1294 readable => \&IO::AIO::poll_cb);
1295
1296 # Danga::Socket integration
1297 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
1298 \&IO::AIO::poll_cb);
1098 1299
1099 FORK BEHAVIOUR 1300 FORK BEHAVIOUR
1100 This module should do "the right thing" when the process using it forks: 1301 This module should do "the right thing" when the process using it forks:
1101 1302
1102 Before the fork, IO::AIO enters a quiescent state where no requests can 1303 Before the fork, IO::AIO enters a quiescent state where no requests can

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines