… | |
… | |
2 | IO::AIO - Asynchronous Input/Output |
2 | IO::AIO - Asynchronous Input/Output |
3 | |
3 | |
4 | SYNOPSIS |
4 | SYNOPSIS |
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 | |
… | |
… | |
72 | |
72 | |
73 | # register the IO::AIO callback with EV |
73 | # register the IO::AIO callback with EV |
74 | 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; |
75 | |
75 | |
76 | # queue the request to open /etc/passwd |
76 | # queue the request to open /etc/passwd |
77 | aio_open "/etc/passwd", O_RDONLY, 0, sub { |
77 | aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub { |
78 | my $fh = shift |
78 | my $fh = shift |
79 | or die "error while opening: $!"; |
79 | or die "error while opening: $!"; |
80 | |
80 | |
81 | # stat'ing filehandles is generally non-blocking |
81 | # stat'ing filehandles is generally non-blocking |
82 | my $size = -s $fh; |
82 | my $size = -s $fh; |
… | |
… | |
187 | aio_fdatasync $fh, $callback->($status) |
187 | aio_fdatasync $fh, $callback->($status) |
188 | aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) |
188 | aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) |
189 | aio_pathsync $path, $callback->($status) |
189 | aio_pathsync $path, $callback->($status) |
190 | aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $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) |
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) |
192 | aio_group $callback->(...) |
194 | aio_group $callback->(...) |
193 | aio_nop $callback->() |
195 | aio_nop $callback->() |
194 | |
196 | |
195 | $prev_pri = aioreq_pri [$pri] |
197 | $prev_pri = aioreq_pri [$pri] |
196 | aioreq_nice $pri_adjust |
198 | aioreq_nice $pri_adjust |
… | |
… | |
202 | IO::AIO::max_poll_reqs $nreqs |
204 | IO::AIO::max_poll_reqs $nreqs |
203 | IO::AIO::max_poll_time $seconds |
205 | IO::AIO::max_poll_time $seconds |
204 | IO::AIO::min_parallel $nthreads |
206 | IO::AIO::min_parallel $nthreads |
205 | IO::AIO::max_parallel $nthreads |
207 | IO::AIO::max_parallel $nthreads |
206 | IO::AIO::max_idle $nthreads |
208 | IO::AIO::max_idle $nthreads |
|
|
209 | IO::AIO::idle_timeout $seconds |
207 | IO::AIO::max_outstanding $maxreqs |
210 | IO::AIO::max_outstanding $maxreqs |
208 | IO::AIO::nreqs |
211 | IO::AIO::nreqs |
209 | IO::AIO::nready |
212 | IO::AIO::nready |
210 | IO::AIO::npending |
213 | IO::AIO::npending |
211 | |
214 | |
212 | IO::AIO::sendfile $ofh, $ifh, $offset, $count |
215 | IO::AIO::sendfile $ofh, $ifh, $offset, $count |
213 | IO::AIO::fadvise $fh, $offset, $len, $advice |
216 | IO::AIO::fadvise $fh, $offset, $len, $advice |
214 | IO::AIO::mlockall $flags |
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 |
215 | IO::AIO::munlockall |
220 | IO::AIO::munlockall |
216 | |
221 | |
217 | AIO REQUEST FUNCTIONS |
222 | AIO REQUEST FUNCTIONS |
218 | 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 |
219 | with the same name (sans "aio_"). The arguments are similar or |
224 | with the same name (sans "aio_"). The arguments are similar or |
… | |
… | |
292 | 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 |
293 | executed, so better never change the umask. |
298 | executed, so better never change the umask. |
294 | |
299 | |
295 | Example: |
300 | Example: |
296 | |
301 | |
297 | aio_open "/etc/passwd", O_RDONLY, 0, sub { |
302 | aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub { |
298 | if ($_[0]) { |
303 | if ($_[0]) { |
299 | print "open successful, fh is $_[0]\n"; |
304 | print "open successful, fh is $_[0]\n"; |
300 | ... |
305 | ... |
301 | } else { |
306 | } else { |
302 | die "open failed: $!\n"; |
307 | die "open failed: $!\n"; |
… | |
… | |
355 | reading at byte offset $in_offset, and starts writing at the current |
360 | reading at byte offset $in_offset, and starts writing at the current |
356 | file offset of $out_fh. Because of that, it is not safe to issue |
361 | file offset of $out_fh. Because of that, it is not safe to issue |
357 | more than one "aio_sendfile" per $out_fh, as they will interfere |
362 | more than one "aio_sendfile" per $out_fh, as they will interfere |
358 | with each other. |
363 | with each other. |
359 | |
364 | |
|
|
365 | Please note that "aio_sendfile" can read more bytes from $in_fh than |
|
|
366 | are written, and there is no way to find out how many bytes have |
|
|
367 | been read from "aio_sendfile" alone, as "aio_sendfile" only provides |
|
|
368 | the number of bytes written to $out_fh. Only if the result value |
|
|
369 | equals $length one can assume that $length bytes have been read. |
|
|
370 | |
|
|
371 | Unlike with other "aio_" functions, it makes a lot of sense to use |
|
|
372 | "aio_sendfile" on non-blocking sockets, as long as one end |
|
|
373 | (typically the $in_fh) is a file - the file I/O will then be |
|
|
374 | asynchronous, while the socket I/O will be non-blocking. Note, |
|
|
375 | however, that you can run into a trap where "aio_sendfile" reads |
|
|
376 | some data with readahead, then fails to write all data, and when the |
|
|
377 | socket is ready the next time, the data in the cache is already |
|
|
378 | lost, forcing "aio_sendfile" to again hit the disk. Explicit |
|
|
379 | "aio_read" + "aio_write" let's you control resource usage much |
|
|
380 | better. |
|
|
381 | |
360 | This call tries to make use of a native "sendfile" syscall to |
382 | This call tries to make use of a native "sendfile" syscall to |
361 | provide zero-copy operation. For this to work, $out_fh should refer |
383 | provide zero-copy operation. For this to work, $out_fh should refer |
362 | to a socket, and $in_fh should refer to an mmap'able file. |
384 | to a socket, and $in_fh should refer to an mmap'able file. |
363 | |
385 | |
364 | If a native sendfile cannot be found or it fails with "ENOSYS", |
386 | If a native sendfile cannot be found or it fails with "ENOSYS", |
365 | "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK", |
387 | "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK", |
366 | it will be emulated, so you can call "aio_sendfile" on any type of |
388 | it will be emulated, so you can call "aio_sendfile" on any type of |
367 | filehandle regardless of the limitations of the operating system. |
389 | filehandle regardless of the limitations of the operating system. |
368 | |
|
|
369 | Please note, however, that "aio_sendfile" can read more bytes from |
|
|
370 | $in_fh than are written, and there is no way to find out how many |
|
|
371 | bytes have been read from "aio_sendfile" alone, as "aio_sendfile" |
|
|
372 | only provides the number of bytes written to $out_fh. Only if the |
|
|
373 | result value equals $length one can assume that $length bytes have |
|
|
374 | been read. |
|
|
375 | |
390 | |
376 | aio_readahead $fh,$offset,$length, $callback->($retval) |
391 | aio_readahead $fh,$offset,$length, $callback->($retval) |
377 | "aio_readahead" populates the page cache with data from a file so |
392 | "aio_readahead" populates the page cache with data from a file so |
378 | that subsequent reads from that file will not block on disk I/O. The |
393 | that subsequent reads from that file will not block on disk I/O. The |
379 | $offset argument specifies the starting point from which data is to |
394 | $offset argument specifies the starting point from which data is to |
… | |
… | |
399 | |
414 | |
400 | Currently, the stats are always 64-bit-stats, i.e. instead of |
415 | Currently, the stats are always 64-bit-stats, i.e. instead of |
401 | returning an error when stat'ing a large file, the results will be |
416 | returning an error when stat'ing a large file, the results will be |
402 | silently truncated unless perl itself is compiled with large file |
417 | silently truncated unless perl itself is compiled with large file |
403 | support. |
418 | support. |
|
|
419 | |
|
|
420 | To help interpret the mode and dev/rdev stat values, IO::AIO offers |
|
|
421 | the following constants and functions (if not implemented, the |
|
|
422 | constants will be 0 and the functions will either "croak" or fall |
|
|
423 | back on traditional behaviour). |
|
|
424 | |
|
|
425 | "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG", |
|
|
426 | "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t", |
|
|
427 | "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor". |
404 | |
428 | |
405 | Example: Print the length of /etc/passwd: |
429 | Example: Print the length of /etc/passwd: |
406 | |
430 | |
407 | aio_stat "/etc/passwd", sub { |
431 | aio_stat "/etc/passwd", sub { |
408 | $_[0] and die "stat failed: $!"; |
432 | $_[0] and die "stat failed: $!"; |
… | |
… | |
497 | |
521 | |
498 | The only (POSIX-) portable way of calling this function is: |
522 | The only (POSIX-) portable way of calling this function is: |
499 | |
523 | |
500 | aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... |
524 | aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... |
501 | |
525 | |
|
|
526 | See "aio_stat" for info about some potentially helpful extra |
|
|
527 | constants and functions. |
|
|
528 | |
502 | aio_link $srcpath, $dstpath, $callback->($status) |
529 | aio_link $srcpath, $dstpath, $callback->($status) |
503 | Asynchronously create a new link to the existing object at $srcpath |
530 | Asynchronously create a new link to the existing object at $srcpath |
504 | at the path $dstpath and call the callback with the result code. |
531 | at the path $dstpath and call the callback with the result code. |
505 | |
532 | |
506 | aio_symlink $srcpath, $dstpath, $callback->($status) |
533 | aio_symlink $srcpath, $dstpath, $callback->($status) |
… | |
… | |
751 | "aio_msync", above, except for flags, which must be either 0 (which |
778 | "aio_msync", above, except for flags, which must be either 0 (which |
752 | reads all pages and ensures they are instantiated) or |
779 | reads all pages and ensures they are instantiated) or |
753 | "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading |
780 | "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading |
754 | and writing an octet from it, which dirties the page). |
781 | and writing an octet from it, which dirties the page). |
755 | |
782 | |
|
|
783 | aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) |
|
|
784 | This is a rather advanced IO::AIO call, which works best on |
|
|
785 | mmap(2)ed scalars. |
|
|
786 | |
|
|
787 | It reads in all the pages of the underlying storage into memory (if |
|
|
788 | any) and locks them, so they are not getting swapped/paged out or |
|
|
789 | removed. |
|
|
790 | |
|
|
791 | If $length is undefined, then the scalar will be locked till the |
|
|
792 | end. |
|
|
793 | |
|
|
794 | On systems that do not implement "mlock", this function returns -1 |
|
|
795 | and sets errno to "ENOSYS". |
|
|
796 | |
|
|
797 | Note that the corresponding "munlock" is synchronous and is |
|
|
798 | documented under "MISCELLANEOUS FUNCTIONS". |
|
|
799 | |
|
|
800 | Example: open a file, mmap and mlock it - both will be undone when |
|
|
801 | $data gets destroyed. |
|
|
802 | |
|
|
803 | open my $fh, "<", $path or die "$path: $!"; |
|
|
804 | my $data; |
|
|
805 | IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh; |
|
|
806 | aio_mlock $data; # mlock in background |
|
|
807 | |
|
|
808 | aio_mlockall $flags, $callback->($status) |
|
|
809 | Calls the "mlockall" function with the given $flags (a combination |
|
|
810 | of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE"). |
|
|
811 | |
|
|
812 | On systems that do not implement "mlockall", this function returns |
|
|
813 | -1 and sets errno to "ENOSYS". |
|
|
814 | |
|
|
815 | Note that the corresponding "munlockall" is synchronous and is |
|
|
816 | documented under "MISCELLANEOUS FUNCTIONS". |
|
|
817 | |
|
|
818 | Example: asynchronously lock all current and future pages into |
|
|
819 | memory. |
|
|
820 | |
|
|
821 | aio_mlockall IO::AIO::MCL_FUTURE; |
|
|
822 | |
756 | aio_group $callback->(...) |
823 | aio_group $callback->(...) |
757 | This is a very special aio request: Instead of doing something, it |
824 | This is a very special aio request: Instead of doing something, it |
758 | is a container for other aio requests, which is useful if you want |
825 | is a container for other aio requests, which is useful if you want |
759 | to bundle many requests into a single, composite, request with a |
826 | to bundle many requests into a single, composite, request with a |
760 | definite callback and the ability to cancel the whole request with |
827 | definite callback and the ability to cancel the whole request with |
… | |
… | |
1067 | |
1134 | |
1068 | Under normal circumstances you don't need to call this function. |
1135 | Under normal circumstances you don't need to call this function. |
1069 | |
1136 | |
1070 | IO::AIO::max_idle $nthreads |
1137 | IO::AIO::max_idle $nthreads |
1071 | Limit the number of threads (default: 4) that are allowed to idle |
1138 | Limit the number of threads (default: 4) that are allowed to idle |
1072 | (i.e., threads that did not get a request to process within 10 |
1139 | (i.e., threads that did not get a request to process within the idle |
1073 | seconds). That means if a thread becomes idle while $nthreads other |
1140 | timeout (default: 10 seconds). That means if a thread becomes idle |
1074 | threads are also idle, it will free its resources and exit. |
1141 | while $nthreads other threads are also idle, it will free its |
|
|
1142 | resources and exit. |
1075 | |
1143 | |
1076 | This is useful when you allow a large number of threads (e.g. 100 or |
1144 | This is useful when you allow a large number of threads (e.g. 100 or |
1077 | 1000) to allow for extremely high load situations, but want to free |
1145 | 1000) to allow for extremely high load situations, but want to free |
1078 | resources under normal circumstances (1000 threads can easily |
1146 | resources under normal circumstances (1000 threads can easily |
1079 | consume 30MB of RAM). |
1147 | consume 30MB of RAM). |
1080 | |
1148 | |
1081 | The default is probably ok in most situations, especially if thread |
1149 | The default is probably ok in most situations, especially if thread |
1082 | creation is fast. If thread creation is very slow on your system you |
1150 | creation is fast. If thread creation is very slow on your system you |
1083 | might want to use larger values. |
1151 | might want to use larger values. |
|
|
1152 | |
|
|
1153 | IO::AIO::idle_timeout $seconds |
|
|
1154 | Sets the minimum idle timeout (default 10) after which worker |
|
|
1155 | threads are allowed to exit. SEe "IO::AIO::max_idle". |
1084 | |
1156 | |
1085 | IO::AIO::max_outstanding $maxreqs |
1157 | IO::AIO::max_outstanding $maxreqs |
1086 | This is a very bad function to use in interactive programs because |
1158 | This is a very bad function to use in interactive programs because |
1087 | it blocks, and a bad way to reduce concurrency because it is |
1159 | it blocks, and a bad way to reduce concurrency because it is |
1088 | inexact: Better use an "aio_group" together with a feed callback. |
1160 | inexact: Better use an "aio_group" together with a feed callback. |
… | |
… | |
1130 | set to non-blocking operations). |
1202 | set to non-blocking operations). |
1131 | |
1203 | |
1132 | Returns the number of bytes copied, or -1 on error. |
1204 | Returns the number of bytes copied, or -1 on error. |
1133 | |
1205 | |
1134 | IO::AIO::fadvise $fh, $offset, $len, $advice |
1206 | IO::AIO::fadvise $fh, $offset, $len, $advice |
1135 | Simply calls the "posix_fadvise" function (see it's manpage for |
1207 | Simply calls the "posix_fadvise" function (see its manpage for |
1136 | details). The following advice constants are avaiable: |
1208 | details). The following advice constants are avaiable: |
1137 | "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL", |
1209 | "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL", |
1138 | "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE", |
1210 | "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE", |
1139 | "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED". |
1211 | "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED". |
1140 | |
1212 | |
1141 | On systems that do not implement "posix_fadvise", this function |
1213 | On systems that do not implement "posix_fadvise", this function |
1142 | returns ENOSYS, otherwise the return value of "posix_fadvise". |
1214 | returns ENOSYS, otherwise the return value of "posix_fadvise". |
|
|
1215 | |
|
|
1216 | IO::AIO::madvise $scalar, $offset, $len, $advice |
|
|
1217 | Simply calls the "posix_madvise" function (see its manpage for |
|
|
1218 | details). The following advice constants are avaiable: |
|
|
1219 | "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL", |
|
|
1220 | "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED", |
|
|
1221 | "IO::AIO::MADV_DONTNEED". |
|
|
1222 | |
|
|
1223 | On systems that do not implement "posix_madvise", this function |
|
|
1224 | returns ENOSYS, otherwise the return value of "posix_madvise". |
|
|
1225 | |
|
|
1226 | IO::AIO::mprotect $scalar, $offset, $len, $protect |
|
|
1227 | Simply calls the "mprotect" function on the preferably AIO::mmap'ed |
|
|
1228 | $scalar (see its manpage for details). The following protect |
|
|
1229 | constants are avaiable: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ", |
|
|
1230 | "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC". |
|
|
1231 | |
|
|
1232 | On systems that do not implement "mprotect", this function returns |
|
|
1233 | ENOSYS, otherwise the return value of "mprotect". |
1143 | |
1234 | |
1144 | IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] |
1235 | IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] |
1145 | Memory-maps a file (or anonymous memory range) and attaches it to |
1236 | Memory-maps a file (or anonymous memory range) and attaches it to |
1146 | the given $scalar, which will act like a string scalar. |
1237 | the given $scalar, which will act like a string scalar. |
1147 | |
1238 | |
… | |
… | |
1192 | my $fast_md5 = md5 $data; |
1283 | my $fast_md5 = md5 $data; |
1193 | |
1284 | |
1194 | IO::AIO::munmap $scalar |
1285 | IO::AIO::munmap $scalar |
1195 | Removes a previous mmap and undefines the $scalar. |
1286 | Removes a previous mmap and undefines the $scalar. |
1196 | |
1287 | |
1197 | IO::AIO::mlockall $flags |
1288 | IO::AIO::munlock $scalar, $offset = 0, $length = undef |
1198 | Calls the "mlockall" function with the given $flags (a combination |
1289 | Calls the "munlock" function, undoing the effects of a previous |
1199 | of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL__FUTURE"). |
1290 | "aio_mlock" call (see its description for details). |
1200 | |
|
|
1201 | On systems that do not implement "mlockall", this function returns |
|
|
1202 | ENOSYS, otherwise the return value of "mlockall". |
|
|
1203 | |
1291 | |
1204 | IO::AIO::munlockall |
1292 | IO::AIO::munlockall |
1205 | Calls the "munlockall" function. |
1293 | Calls the "munlockall" function. |
1206 | |
1294 | |
1207 | On systems that do not implement "munlockall", this function returns |
1295 | On systems that do not implement "munlockall", this function returns |