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

Comparing IO-AIO/README (file contents):
Revision 1.51 by root, Sat Apr 7 00:50:33 2012 UTC vs.
Revision 1.70 by root, Sat Apr 1 02:14:05 2023 UTC

1NAME 1NAME
2 IO::AIO - Asynchronous Input/Output 2 IO::AIO - Asynchronous/Advanced Input/Output
3 3
4SYNOPSIS 4SYNOPSIS
5 use IO::AIO; 5 use IO::AIO;
6 6
7 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub { 7 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
… …
55 not well-supported or restricted (GNU/Linux doesn't allow them on normal 55 not well-supported or restricted (GNU/Linux doesn't allow them on normal
56 files currently, for example), and they would only support aio_read and 56 files currently, for example), and they would only support aio_read and
57 aio_write, so the remaining functionality would have to be implemented 57 aio_write, so the remaining functionality would have to be implemented
58 using threads anyway. 58 using threads anyway.
59 59
60 In addition to asynchronous I/O, this module also exports some rather
61 arcane interfaces, such as "madvise" or linux's "splice" system call,
62 which is why the "A" in "AIO" can also mean *advanced*.
63
60 Although the module will work in the presence of other (Perl-) threads, 64 Although the module will work in the presence of other (Perl-) threads,
61 it is currently not reentrant in any way, so use appropriate locking 65 it is currently not reentrant in any way, so use appropriate locking
62 yourself, always call "poll_cb" from within the same thread, or never 66 yourself, always call "poll_cb" from within the same thread, or never
63 call "poll_cb" (or other "aio_" functions) recursively. 67 call "poll_cb" (or other "aio_" functions) recursively.
64 68
65 EXAMPLE 69 EXAMPLE
66 This is a simple example that uses the EV module and loads /etc/passwd 70 This is a simple example that uses the EV module and loads /etc/passwd
67 asynchronously: 71 asynchronously:
68 72
69 use Fcntl;
70 use EV; 73 use EV;
71 use IO::AIO; 74 use IO::AIO;
72 75
73 # register the IO::AIO callback with EV 76 # register the IO::AIO callback with EV
74 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 77 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
… …
91 94
92 # file contents now in $contents 95 # file contents now in $contents
93 print $contents; 96 print $contents;
94 97
95 # exit event loop and program 98 # exit event loop and program
96 EV::unloop; 99 EV::break;
97 }; 100 };
98 }; 101 };
99 102
100 # possibly queue up other requests, or open GUI windows, 103 # possibly queue up other requests, or open GUI windows,
101 # check for sockets etc. etc. 104 # check for sockets etc. etc.
102 105
103 # process events as long as there are some: 106 # process events as long as there are some:
104 EV::loop; 107 EV::run;
105 108
106REQUEST ANATOMY AND LIFETIME 109REQUEST ANATOMY AND LIFETIME
107 Every "aio_*" function creates a request. which is a C data structure 110 Every "aio_*" function creates a request. which is a C data structure
108 not directly visible to Perl. 111 not directly visible to Perl.
109 112
… …
146 the actual aio request is severed and calling its methods will 149 the actual aio request is severed and calling its methods will
147 either do nothing or result in a runtime error). 150 either do nothing or result in a runtime error).
148 151
149FUNCTIONS 152FUNCTIONS
150 QUICK OVERVIEW 153 QUICK OVERVIEW
151 This section simply lists the prototypes of the most important functions 154 This section simply lists the prototypes most of the functions for quick
152 for quick reference. See the following sections for function-by-function 155 reference. See the following sections for function-by-function
153 documentation. 156 documentation.
154 157
155 aio_wd $pathname, $callback->($wd) 158 aio_wd $pathname, $callback->($wd)
156 aio_open $pathname, $flags, $mode, $callback->($fh) 159 aio_open $pathname, $flags, $mode, $callback->($fh)
157 aio_close $fh, $callback->($status) 160 aio_close $fh, $callback->($status)
… …
165 aio_statvfs $fh_or_path, $callback->($statvfs) 168 aio_statvfs $fh_or_path, $callback->($statvfs)
166 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 169 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
167 aio_chown $fh_or_path, $uid, $gid, $callback->($status) 170 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
168 aio_chmod $fh_or_path, $mode, $callback->($status) 171 aio_chmod $fh_or_path, $mode, $callback->($status)
169 aio_truncate $fh_or_path, $offset, $callback->($status) 172 aio_truncate $fh_or_path, $offset, $callback->($status)
173 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
174 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
170 aio_unlink $pathname, $callback->($status) 175 aio_unlink $pathname, $callback->($status)
171 aio_mknod $pathname, $mode, $dev, $callback->($status) 176 aio_mknod $pathname, $mode, $dev, $callback->($status)
172 aio_link $srcpath, $dstpath, $callback->($status) 177 aio_link $srcpath, $dstpath, $callback->($status)
173 aio_symlink $srcpath, $dstpath, $callback->($status) 178 aio_symlink $srcpath, $dstpath, $callback->($status)
174 aio_readlink $pathname, $callback->($link) 179 aio_readlink $pathname, $callback->($link)
175 aio_realpath $pathname, $callback->($link) 180 aio_realpath $pathname, $callback->($path)
176 aio_rename $srcpath, $dstpath, $callback->($status) 181 aio_rename $srcpath, $dstpath, $callback->($status)
182 aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
177 aio_mkdir $pathname, $mode, $callback->($status) 183 aio_mkdir $pathname, $mode, $callback->($status)
178 aio_rmdir $pathname, $callback->($status) 184 aio_rmdir $pathname, $callback->($status)
179 aio_readdir $pathname, $callback->($entries) 185 aio_readdir $pathname, $callback->($entries)
180 aio_readdirx $pathname, $flags, $callback->($entries, $flags) 186 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
181 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST 187 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
… …
183 aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs) 189 aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
184 aio_load $pathname, $data, $callback->($status) 190 aio_load $pathname, $data, $callback->($status)
185 aio_copy $srcpath, $dstpath, $callback->($status) 191 aio_copy $srcpath, $dstpath, $callback->($status)
186 aio_move $srcpath, $dstpath, $callback->($status) 192 aio_move $srcpath, $dstpath, $callback->($status)
187 aio_rmtree $pathname, $callback->($status) 193 aio_rmtree $pathname, $callback->($status)
194 aio_fcntl $fh, $cmd, $arg, $callback->($status)
195 aio_ioctl $fh, $request, $buf, $callback->($status)
188 aio_sync $callback->($status) 196 aio_sync $callback->($status)
189 aio_syncfs $fh, $callback->($status) 197 aio_syncfs $fh, $callback->($status)
190 aio_fsync $fh, $callback->($status) 198 aio_fsync $fh, $callback->($status)
191 aio_fdatasync $fh, $callback->($status) 199 aio_fdatasync $fh, $callback->($status)
192 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 200 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
193 aio_pathsync $pathname, $callback->($status) 201 aio_pathsync $pathname, $callback->($status)
194 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 202 aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
195 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 203 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
196 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) 204 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
197 aio_mlockall $flags, $callback->($status) 205 aio_mlockall $flags, $callback->($status)
198 aio_group $callback->(...) 206 aio_group $callback->(...)
199 aio_nop $callback->() 207 aio_nop $callback->()
… …
213 IO::AIO::idle_timeout $seconds 221 IO::AIO::idle_timeout $seconds
214 IO::AIO::max_outstanding $maxreqs 222 IO::AIO::max_outstanding $maxreqs
215 IO::AIO::nreqs 223 IO::AIO::nreqs
216 IO::AIO::nready 224 IO::AIO::nready
217 IO::AIO::npending 225 IO::AIO::npending
226 IO::AIO::reinit
227
228 $nfd = IO::AIO::get_fdlimit
229 IO::AIO::min_fdlimit $nfd
218 230
219 IO::AIO::sendfile $ofh, $ifh, $offset, $count 231 IO::AIO::sendfile $ofh, $ifh, $offset, $count
220 IO::AIO::fadvise $fh, $offset, $len, $advice 232 IO::AIO::fadvise $fh, $offset, $len, $advice
233 IO::AIO::fexecve $fh, $argv, $envp
234
235 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
236 IO::AIO::munmap $scalar
237 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
221 IO::AIO::madvise $scalar, $offset, $length, $advice 238 IO::AIO::madvise $scalar, $offset, $length, $advice
222 IO::AIO::mprotect $scalar, $offset, $length, $protect 239 IO::AIO::mprotect $scalar, $offset, $length, $protect
223 IO::AIO::munlock $scalar, $offset = 0, $length = undef 240 IO::AIO::munlock $scalar, $offset = 0, $length = undef
224 IO::AIO::munlockall 241 IO::AIO::munlockall
242
243 # stat extensions
244 $counter = IO::AIO::st_gen
245 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
246 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
247 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
248 $seconds = IO::AIO::st_btimesec
249 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
250
251 # very much unportable syscalls
252 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
253 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
254 IO::AIO::tee $r_fh, $w_fh, $length, $flags
255
256 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
257 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
258
259 $fh = IO::AIO::eventfd [$initval, [$flags]]
260 $fh = IO::AIO::memfd_create $pathname[, $flags]
261
262 $fh = IO::AIO::timerfd_create $clockid[, $flags]
263 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
264 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
265
266 $fh = IO::AIO::pidfd_open $pid[, $flags]
267 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
268 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
269
270 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
271 $retval = IO::AIO::umount $path, $flags = 0
225 272
226 API NOTES 273 API NOTES
227 All the "aio_*" calls are more or less thin wrappers around the syscall 274 All the "aio_*" calls are more or less thin wrappers around the syscall
228 with the same name (sans "aio_"). The arguments are similar or 275 with the same name (sans "aio_"). The arguments are similar or
229 identical, and they all accept an additional (and optional) $callback 276 identical, and they all accept an additional (and optional) $callback
… …
293 Similar to "aioreq_pri", but subtracts the given value from the 340 Similar to "aioreq_pri", but subtracts the given value from the
294 current priority, so the effect is cumulative. 341 current priority, so the effect is cumulative.
295 342
296 aio_open $pathname, $flags, $mode, $callback->($fh) 343 aio_open $pathname, $flags, $mode, $callback->($fh)
297 Asynchronously open or create a file and call the callback with a 344 Asynchronously open or create a file and call the callback with a
298 newly created filehandle for the file. 345 newly created filehandle for the file (or "undef" in case of an
299 346 error).
300 The pathname passed to "aio_open" must be absolute. See API NOTES,
301 above, for an explanation.
302 347
303 The $flags argument is a bitmask. See the "Fcntl" module for a list. 348 The $flags argument is a bitmask. See the "Fcntl" module for a list.
304 They are the same as used by "sysopen". 349 They are the same as used by "sysopen".
305 350
306 Likewise, $mode specifies the mode of the newly created file, if it 351 Likewise, $mode specifies the mode of the newly created file, if it
… …
326 "O_APPEND"), the following POSIX and non-POSIX constants are 371 "O_APPEND"), the following POSIX and non-POSIX constants are
327 available (missing ones on your system are, as usual, 0): 372 available (missing ones on your system are, as usual, 0):
328 373
329 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY", 374 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
330 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY", 375 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
331 "O_DSYNC", "O_RSYNC", "O_SYNC" and "O_TTY_INIT". 376 "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", "O_TTY_INIT"
377 and "O_ACCMODE".
332 378
333 aio_close $fh, $callback->($status) 379 aio_close $fh, $callback->($status)
334 Asynchronously close a file and call the callback with the result 380 Asynchronously close a file and call the callback with the result
335 code. 381 code.
336 382
… …
356 402
357 In theory, the $whence constants could be different than the 403 In theory, the $whence constants could be different than the
358 corresponding values from Fcntl, but perl guarantees they are the 404 corresponding values from Fcntl, but perl guarantees they are the
359 same, so don't panic. 405 same, so don't panic.
360 406
407 As a GNU/Linux (and maybe Solaris) extension, also the constants
408 "IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if they
409 could be found. No guarantees about suitability for use in
410 "aio_seek" or Perl's "sysseek" can be made though, although I would
411 naively assume they "just work".
412
361 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 413 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
362 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 414 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
363 Reads or writes $length bytes from or to the specified $fh and 415 Reads or writes $length bytes from or to the specified $fh and
364 $offset into the scalar given by $data and offset $dataoffset and 416 $offset into the scalar given by $data and offset $dataoffset and
365 calls the callback without the actual number of bytes read (or -1 on 417 calls the callback with the actual number of bytes transferred (or
366 error, just like the syscall). 418 -1 on error, just like the syscall).
367 419
368 "aio_read" will, like "sysread", shrink or grow the $data scalar to 420 "aio_read" will, like "sysread", shrink or grow the $data scalar to
369 offset plus the actual number of bytes read. 421 offset plus the actual number of bytes read.
370 422
371 If $offset is undefined, then the current file descriptor offset 423 If $offset is undefined, then the current file descriptor offset
… …
428 As native sendfile syscalls (as practically any non-POSIX interface 480 As native sendfile syscalls (as practically any non-POSIX interface
429 hacked together in a hurry to improve benchmark numbers) tend to be 481 hacked together in a hurry to improve benchmark numbers) tend to be
430 rather buggy on many systems, this implementation tries to work 482 rather buggy on many systems, this implementation tries to work
431 around some known bugs in Linux and FreeBSD kernels (probably 483 around some known bugs in Linux and FreeBSD kernels (probably
432 others, too), but that might fail, so you really really should check 484 others, too), but that might fail, so you really really should check
433 the return value of "aio_sendfile" - fewre bytes than expected might 485 the return value of "aio_sendfile" - fewer bytes than expected might
434 have been transferred. 486 have been transferred.
435 487
436 aio_readahead $fh,$offset,$length, $callback->($retval) 488 aio_readahead $fh,$offset,$length, $callback->($retval)
437 "aio_readahead" populates the page cache with data from a file so 489 "aio_readahead" populates the page cache with data from a file so
438 that subsequent reads from that file will not block on disk I/O. The 490 that subsequent reads from that file will not block on disk I/O. The
… …
442 to a page boundary and bytes are read up to the next page boundary 494 to a page boundary and bytes are read up to the next page boundary
443 greater than or equal to (off-set+length). "aio_readahead" does not 495 greater than or equal to (off-set+length). "aio_readahead" does not
444 read beyond the end of the file. The current file offset of the file 496 read beyond the end of the file. The current file offset of the file
445 is left unchanged. 497 is left unchanged.
446 498
447 If that syscall doesn't exist (likely if your OS isn't Linux) it 499 If that syscall doesn't exist (likely if your kernel isn't Linux) it
448 will be emulated by simply reading the data, which would have a 500 will be emulated by simply reading the data, which would have a
449 similar effect. 501 similar effect.
450 502
451 aio_stat $fh_or_path, $callback->($status) 503 aio_stat $fh_or_path, $callback->($status)
452 aio_lstat $fh, $callback->($status) 504 aio_lstat $fh, $callback->($status)
453 Works like perl's "stat" or "lstat" in void context. The callback 505 Works almost exactly like perl's "stat" or "lstat" in void context.
454 will be called after the stat and the results will be available 506 The callback will be called after the stat and the results will be
455 using "stat _" or "-s _" etc... 507 available using "stat _" or "-s _" and other tests (with the
456 508 exception of "-B" and "-T").
457 The pathname passed to "aio_stat" must be absolute. See API NOTES,
458 above, for an explanation.
459 509
460 Currently, the stats are always 64-bit-stats, i.e. instead of 510 Currently, the stats are always 64-bit-stats, i.e. instead of
461 returning an error when stat'ing a large file, the results will be 511 returning an error when stat'ing a large file, the results will be
462 silently truncated unless perl itself is compiled with large file 512 silently truncated unless perl itself is compiled with large file
463 support. 513 support.
… …
468 back on traditional behaviour). 518 back on traditional behaviour).
469 519
470 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG", 520 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
471 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t", 521 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
472 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor". 522 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
523
524 To access higher resolution stat timestamps, see "SUBSECOND STAT
525 TIME ACCESS".
473 526
474 Example: Print the length of /etc/passwd: 527 Example: Print the length of /etc/passwd:
475 528
476 aio_stat "/etc/passwd", sub { 529 aio_stat "/etc/passwd", sub {
477 $_[0] and die "stat failed: $!"; 530 $_[0] and die "stat failed: $!";
… …
524 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 577 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
525 Works like perl's "utime" function (including the special case of 578 Works like perl's "utime" function (including the special case of
526 $atime and $mtime being undef). Fractional times are supported if 579 $atime and $mtime being undef). Fractional times are supported if
527 the underlying syscalls support them. 580 the underlying syscalls support them.
528 581
529 When called with a pathname, uses utimes(2) if available, otherwise 582 When called with a pathname, uses utimensat(2) or utimes(2) if
530 utime(2). If called on a file descriptor, uses futimes(2) if 583 available, otherwise utime(2). If called on a file descriptor, uses
531 available, otherwise returns ENOSYS, so this is not portable. 584 futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
585 this is not portable.
532 586
533 Examples: 587 Examples:
534 588
535 # set atime and mtime to current time (basically touch(1)): 589 # set atime and mtime to current time (basically touch(1)):
536 aio_utime "path", undef, undef; 590 aio_utime "path", undef, undef;
… …
550 aio_chown "path", 0, undef; 604 aio_chown "path", 0, undef;
551 605
552 aio_truncate $fh_or_path, $offset, $callback->($status) 606 aio_truncate $fh_or_path, $offset, $callback->($status)
553 Works like truncate(2) or ftruncate(2). 607 Works like truncate(2) or ftruncate(2).
554 608
609 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
610 Allocates or frees disk space according to the $mode argument. See
611 the linux "fallocate" documentation for details.
612
613 $mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
614 space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
615 IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
616
617 IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
618 (without leaving a hole), "FALLOC_FL_ZERO_RANGE", to zero a range,
619 "FALLOC_FL_INSERT_RANGE" to insert a range and
620 "FALLOC_FL_UNSHARE_RANGE" to unshare shared blocks (see your
621 fallocate(2) manpage).
622
623 The file system block size used by "fallocate" is presumably the
624 "f_bsize" returned by "statvfs", but different filesystems and
625 filetypes can dictate other limitations.
626
627 If "fallocate" isn't available or cannot be emulated (currently no
628 emulation will be attempted), passes -1 and sets $! to "ENOSYS".
629
555 aio_chmod $fh_or_path, $mode, $callback->($status) 630 aio_chmod $fh_or_path, $mode, $callback->($status)
556 Works like perl's "chmod" function. 631 Works like perl's "chmod" function.
557 632
558 aio_unlink $pathname, $callback->($status) 633 aio_unlink $pathname, $callback->($status)
559 Asynchronously unlink (delete) a file and call the callback with the 634 Asynchronously unlink (delete) a file and call the callback with the
… …
585 the callback. If an error occurs, nothing or undef gets passed to 660 the callback. If an error occurs, nothing or undef gets passed to
586 the callback. 661 the callback.
587 662
588 aio_realpath $pathname, $callback->($path) 663 aio_realpath $pathname, $callback->($path)
589 Asynchronously make the path absolute and resolve any symlinks in 664 Asynchronously make the path absolute and resolve any symlinks in
590 $path. The resulting path only consists of directories (Same as 665 $path. The resulting path only consists of directories (same as
591 Cwd::realpath). 666 Cwd::realpath).
592 667
593 This request can be used to get the absolute path of the current 668 This request can be used to get the absolute path of the current
594 working directory by passing it a path of . (a single dot). 669 working directory by passing it a path of . (a single dot).
595 670
596 aio_rename $srcpath, $dstpath, $callback->($status) 671 aio_rename $srcpath, $dstpath, $callback->($status)
597 Asynchronously rename the object at $srcpath to $dstpath, just as 672 Asynchronously rename the object at $srcpath to $dstpath, just as
598 rename(2) and call the callback with the result code. 673 rename(2) and call the callback with the result code.
674
675 On systems that support the AIO::WD working directory abstraction
676 natively, the case "[$wd, "."]" as $srcpath is specialcased -
677 instead of failing, "rename" is called on the absolute path of $wd.
678
679 aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
680 Basically a version of "aio_rename" with an additional $flags
681 argument. Calling this with "$flags=0" is the same as calling
682 "aio_rename".
683
684 Non-zero flags are currently only supported on GNU/Linux systems
685 that support renameat2. Other systems fail with "ENOSYS" in this
686 case.
687
688 The following constants are available (missing ones are, as usual
689 0), see renameat2(2) for details:
690
691 "IO::AIO::RENAME_NOREPLACE", "IO::AIO::RENAME_EXCHANGE" and
692 "IO::AIO::RENAME_WHITEOUT".
599 693
600 aio_mkdir $pathname, $mode, $callback->($status) 694 aio_mkdir $pathname, $mode, $callback->($status)
601 Asynchronously mkdir (create) a directory and call the callback with 695 Asynchronously mkdir (create) a directory and call the callback with
602 the result code. $mode will be modified by the umask at the time the 696 the result code. $mode will be modified by the umask at the time the
603 request is executed, so do not change your umask. 697 request is executed, so do not change your umask.
604 698
605 aio_rmdir $pathname, $callback->($status) 699 aio_rmdir $pathname, $callback->($status)
606 Asynchronously rmdir (delete) a directory and call the callback with 700 Asynchronously rmdir (delete) a directory and call the callback with
607 the result code. 701 the result code.
608 702
703 On systems that support the AIO::WD working directory abstraction
704 natively, the case "[$wd, "."]" is specialcased - instead of
705 failing, "rmdir" is called on the absolute path of $wd.
706
609 aio_readdir $pathname, $callback->($entries) 707 aio_readdir $pathname, $callback->($entries)
610 Unlike the POSIX call of the same name, "aio_readdir" reads an 708 Unlike the POSIX call of the same name, "aio_readdir" reads an
611 entire directory (i.e. opendir + readdir + closedir). The entries 709 entire directory (i.e. opendir + readdir + closedir). The entries
612 will not be sorted, and will NOT include the "." and ".." entries. 710 will not be sorted, and will NOT include the "." and ".." entries.
613 711
… …
622 The flags are a combination of the following constants, ORed 720 The flags are a combination of the following constants, ORed
623 together (the flags will also be passed to the callback, possibly 721 together (the flags will also be passed to the callback, possibly
624 modified): 722 modified):
625 723
626 IO::AIO::READDIR_DENTS 724 IO::AIO::READDIR_DENTS
627 When this flag is off, then the callback gets an arrayref 725 Normally the callback gets an arrayref consisting of names only
628 consisting of names only (as with "aio_readdir"), otherwise it 726 (as with "aio_readdir"). If this flag is set, then the callback
629 gets an arrayref with "[$name, $type, $inode]" arrayrefs, each 727 gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
630 describing a single directory entry in more detail. 728 describing a single directory entry in more detail:
631 729
632 $name is the name of the entry. 730 $name is the name of the entry.
633 731
634 $type is one of the "IO::AIO::DT_xxx" constants: 732 $type is one of the "IO::AIO::DT_xxx" constants:
635 733
636 "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR", 734 "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
637 "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG", 735 "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
638 "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT". 736 "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
639 737
640 "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If 738 "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
641 you need to know, you have to run stat yourself. Also, for speed 739 you need to know, you have to run stat yourself. Also, for
642 reasons, the $type scalars are read-only: you can not modify 740 speed/memory reasons, the $type scalars are read-only: you must
643 them. 741 not modify them.
644 742
645 $inode is the inode number (which might not be exact on systems 743 $inode is the inode number (which might not be exact on systems
646 with 64 bit inode numbers and 32 bit perls). This field has 744 with 64 bit inode numbers and 32 bit perls). This field has
647 unspecified content on systems that do not deliver the inode 745 unspecified content on systems that do not deliver the inode
648 information. 746 information.
… …
660 of which names with short names are tried first. 758 of which names with short names are tried first.
661 759
662 IO::AIO::READDIR_STAT_ORDER 760 IO::AIO::READDIR_STAT_ORDER
663 When this flag is set, then the names will be returned in an 761 When this flag is set, then the names will be returned in an
664 order suitable for stat()'ing each one. That is, when you plan 762 order suitable for stat()'ing each one. That is, when you plan
665 to stat() all files in the given directory, then the returned 763 to stat() most or all files in the given directory, then the
666 order will likely be fastest. 764 returned order will likely be faster.
667 765
668 If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are 766 If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
669 specified, then the likely dirs come first, resulting in a less 767 specified, then the likely dirs come first, resulting in a less
670 optimal stat order. 768 optimal stat order for stat'ing all entries, but likely a more
769 optimal order for finding subdirectories.
671 770
672 IO::AIO::READDIR_FOUND_UNKNOWN 771 IO::AIO::READDIR_FOUND_UNKNOWN
673 This flag should not be set when calling "aio_readdirx". 772 This flag should not be set when calling "aio_readdirx".
674 Instead, it is being set by "aio_readdirx", when any of the 773 Instead, it is being set by "aio_readdirx", when any of the
675 $type's found were "IO::AIO::DT_UNKNOWN". The absence of this 774 $type's found were "IO::AIO::DT_UNKNOWN". The absence of this
676 flag therefore indicates that all $type's are known, which can 775 flag therefore indicates that all $type's are known, which can
677 be used to speed up some algorithms. 776 be used to speed up some algorithms.
678 777
778 aio_slurp $pathname, $offset, $length, $data, $callback->($status)
779 Opens, reads and closes the given file. The data is put into $data,
780 which is resized as required.
781
782 If $offset is negative, then it is counted from the end of the file.
783
784 If $length is zero, then the remaining length of the file is used.
785 Also, in this case, the same limitations to modifying $data apply as
786 when IO::AIO::mmap is used, i.e. it must only be modified in-place
787 with "substr". If the size of the file is known, specifying a
788 non-zero $length results in a performance advantage.
789
790 This request is similar to the older "aio_load" request, but since
791 it is a single request, it might be more efficient to use.
792
793 Example: load /etc/passwd into $passwd.
794
795 my $passwd;
796 aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
797 $_[0] >= 0
798 or die "/etc/passwd: $!\n";
799
800 printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
801 print $passwd;
802 };
803 IO::AIO::flush;
804
679 aio_load $pathname, $data, $callback->($status) 805 aio_load $pathname, $data, $callback->($status)
680 This is a composite request that tries to fully load the given file 806 This is a composite request that tries to fully load the given file
681 into memory. Status is the same as with aio_read. 807 into memory. Status is the same as with aio_read.
808
809 Using "aio_slurp" might be more efficient, as it is a single
810 request.
682 811
683 aio_copy $srcpath, $dstpath, $callback->($status) 812 aio_copy $srcpath, $dstpath, $callback->($status)
684 Try to copy the *file* (directories not supported as either source 813 Try to copy the *file* (directories not supported as either source
685 or destination) from $srcpath to $dstpath and call the callback with 814 or destination) from $srcpath to $dstpath and call the callback with
686 a status of 0 (ok) or -1 (error, see $!). 815 a status of 0 (ok) or -1 (error, see $!).
816
817 Existing destination files will be truncated.
687 818
688 This is a composite request that creates the destination file with 819 This is a composite request that creates the destination file with
689 mode 0200 and copies the contents of the source file into it using 820 mode 0200 and copies the contents of the source file into it using
690 "aio_sendfile", followed by restoring atime, mtime, access mode and 821 "aio_sendfile", followed by restoring atime, mtime, access mode and
691 uid/gid, in that order. 822 uid/gid, in that order.
… …
708 to efficiently separate the entries of directory $path into two sets 839 to efficiently separate the entries of directory $path into two sets
709 of names, directories you can recurse into (directories), and ones 840 of names, directories you can recurse into (directories), and ones
710 you cannot recurse into (everything else, including symlinks to 841 you cannot recurse into (everything else, including symlinks to
711 directories). 842 directories).
712 843
713 "aio_scandir" is a composite request that creates of many sub 844 "aio_scandir" is a composite request that generates many sub
714 requests_ $maxreq specifies the maximum number of outstanding aio 845 requests. $maxreq specifies the maximum number of outstanding aio
715 requests that this function generates. If it is "<= 0", then a 846 requests that this function generates. If it is "<= 0", then a
716 suitable default will be chosen (currently 4). 847 suitable default will be chosen (currently 4).
717 848
718 On error, the callback is called without arguments, otherwise it 849 On error, the callback is called without arguments, otherwise it
719 receives two array-refs with path-relative entry names. 850 receives two array-refs with path-relative entry names.
… …
766 Delete a directory tree starting (and including) $path, return the 897 Delete a directory tree starting (and including) $path, return the
767 status of the final "rmdir" only. This is a composite request that 898 status of the final "rmdir" only. This is a composite request that
768 uses "aio_scandir" to recurse into and rmdir directories, and unlink 899 uses "aio_scandir" to recurse into and rmdir directories, and unlink
769 everything else. 900 everything else.
770 901
902 aio_fcntl $fh, $cmd, $arg, $callback->($status)
903 aio_ioctl $fh, $request, $buf, $callback->($status)
904 These work just like the "fcntl" and "ioctl" built-in functions,
905 except they execute asynchronously and pass the return value to the
906 callback.
907
908 Both calls can be used for a lot of things, some of which make more
909 sense to run asynchronously in their own thread, while some others
910 make less sense. For example, calls that block waiting for external
911 events, such as locking, will also lock down an I/O thread while it
912 is waiting, which can deadlock the whole I/O system. At the same
913 time, there might be no alternative to using a thread to wait.
914
915 So in general, you should only use these calls for things that do
916 (filesystem) I/O, not for things that wait for other events
917 (network, other processes), although if you are careful and know
918 what you are doing, you still can.
919
920 The following constants are available and can be used for normal
921 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
922
923 "F_DUPFD_CLOEXEC",
924
925 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
926
927 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
928 "FIDEDUPERANGE".
929
930 "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
931 "F_SEAL_GROW" and "F_SEAL_WRITE".
932
933 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
934 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
935
936 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
937 "FS_IOC_SET_ENCRYPTION_POLICY", "FS_IOC_GET_ENCRYPTION_PWSALT",
938 "FS_IOC_GET_ENCRYPTION_POLICY", "FS_KEY_DESCRIPTOR_SIZE".
939
940 "FS_SECRM_FL", "FS_UNRM_FL", "FS_COMPR_FL", "FS_SYNC_FL",
941 "FS_IMMUTABLE_FL", "FS_APPEND_FL", "FS_NODUMP_FL", "FS_NOATIME_FL",
942 "FS_DIRTY_FL", "FS_COMPRBLK_FL", "FS_NOCOMP_FL", "FS_ENCRYPT_FL",
943 "FS_BTREE_FL", "FS_INDEX_FL", "FS_JOURNAL_DATA_FL", "FS_NOTAIL_FL",
944 "FS_DIRSYNC_FL", "FS_TOPDIR_FL", "FS_FL_USER_MODIFIABLE".
945
946 "FS_XFLAG_REALTIME", "FS_XFLAG_PREALLOC", "FS_XFLAG_IMMUTABLE",
947 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
948 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
949 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
950 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
951 "FS_XFLAG_HASATTR",
952
953 "BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
954 "BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
955 "BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET", "BLKGETSIZE64",
956
771 aio_sync $callback->($status) 957 aio_sync $callback->($status)
772 Asynchronously call sync and call the callback when finished. 958 Asynchronously call sync and call the callback when finished.
773 959
774 aio_fsync $fh, $callback->($status) 960 aio_fsync $fh, $callback->($status)
775 Asynchronously call fsync on the given filehandle and call the 961 Asynchronously call fsync on the given filehandle and call the
… …
811 Future versions of this function might fall back to other methods 997 Future versions of this function might fall back to other methods
812 when "fsync" on the directory fails (such as calling "sync"). 998 when "fsync" on the directory fails (such as calling "sync").
813 999
814 Passes 0 when everything went ok, and -1 on error. 1000 Passes 0 when everything went ok, and -1 on error.
815 1001
816 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, 1002 aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC,
817 $callback->($status) 1003 $callback->($status)
818 This is a rather advanced IO::AIO call, which only works on 1004 This is a rather advanced IO::AIO call, which only works on
819 mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it 1005 mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
820 also works on data scalars managed by the Sys::Mmap or Mmap modules, 1006 also works on data scalars managed by the Sys::Mmap or Mmap modules,
821 note that the scalar must only be modified in-place while an aio 1007 note that the scalar must only be modified in-place while an aio
… …
823 1009
824 It calls the "msync" function of your OS, if available, with the 1010 It calls the "msync" function of your OS, if available, with the
825 memory area starting at $offset in the string and ending $length 1011 memory area starting at $offset in the string and ending $length
826 bytes later. If $length is negative, counts from the end, and if 1012 bytes later. If $length is negative, counts from the end, and if
827 $length is "undef", then it goes till the end of the string. The 1013 $length is "undef", then it goes till the end of the string. The
828 flags can be a combination of "IO::AIO::MS_ASYNC", 1014 flags can be either "IO::AIO::MS_ASYNC" or "IO::AIO::MS_SYNC", plus
829 "IO::AIO::MS_INVALIDATE" and "IO::AIO::MS_SYNC". 1015 an optional "IO::AIO::MS_INVALIDATE".
830 1016
831 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, 1017 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
832 $callback->($status) 1018 $callback->($status)
833 This is a rather advanced IO::AIO call, which works best on 1019 This is a rather advanced IO::AIO call, which works best on
834 mmap(2)ed scalars. 1020 mmap(2)ed scalars.
835 1021
836 It touches (reads or writes) all memory pages in the specified range 1022 It touches (reads or writes) all memory pages in the specified range
837 inside the scalar. All caveats and parameters are the same as for 1023 inside the scalar. All caveats and parameters are the same as for
838 "aio_msync", above, except for flags, which must be either 0 (which 1024 "aio_msync", above, except for flags, which must be either 0 (which
839 reads all pages and ensures they are instantiated) or 1025 reads all pages and ensures they are instantiated) or
840 "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading 1026 "IO::AIO::MT_MODIFY", which modifies the memory pages (by reading
841 and writing an octet from it, which dirties the page). 1027 and writing an octet from it, which dirties the page).
842 1028
843 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) 1029 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
844 This is a rather advanced IO::AIO call, which works best on 1030 This is a rather advanced IO::AIO call, which works best on
845 mmap(2)ed scalars. 1031 mmap(2)ed scalars.
… …
865 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh; 1051 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
866 aio_mlock $data; # mlock in background 1052 aio_mlock $data; # mlock in background
867 1053
868 aio_mlockall $flags, $callback->($status) 1054 aio_mlockall $flags, $callback->($status)
869 Calls the "mlockall" function with the given $flags (a combination 1055 Calls the "mlockall" function with the given $flags (a combination
870 of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE"). 1056 of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
1057 "IO::AIO::MCL_ONFAULT").
871 1058
872 On systems that do not implement "mlockall", this function returns 1059 On systems that do not implement "mlockall", this function returns
873 -1 and sets errno to "ENOSYS". 1060 -1 and sets errno to "ENOSYS". Similarly, flag combinations not
1061 supported by the system result in a return value of -1 with errno
1062 being set to "EINVAL".
874 1063
875 Note that the corresponding "munlockall" is synchronous and is 1064 Note that the corresponding "munlockall" is synchronous and is
876 documented under "MISCELLANEOUS FUNCTIONS". 1065 documented under "MISCELLANEOUS FUNCTIONS".
877 1066
878 Example: asynchronously lock all current and future pages into 1067 Example: asynchronously lock all current and future pages into
879 memory. 1068 memory.
880 1069
881 aio_mlockall IO::AIO::MCL_FUTURE; 1070 aio_mlockall IO::AIO::MCL_FUTURE;
882 1071
883 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents) 1072 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
884 Queries the extents of the given file (by calling the Linux FIEMAP 1073 Queries the extents of the given file (by calling the Linux "FIEMAP"
885 ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for 1074 ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for
886 details). If the "ioctl" is not available on your OS, then this 1075 details). If the ioctl is not available on your OS, then this
887 rquiest will fail with "ENOSYS". 1076 request will fail with "ENOSYS".
888 1077
889 $start is the starting offset to query extents for, $length is the 1078 $start is the starting offset to query extents for, $length is the
890 size of the range to query - if it is "undef", then the whole file 1079 size of the range to query - if it is "undef", then the whole file
891 will be queried. 1080 will be queried.
892 1081
… …
894 "IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is 1083 "IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
895 also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to 1084 also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
896 query the data portion. 1085 query the data portion.
897 1086
898 $count is the maximum number of extent records to return. If it is 1087 $count is the maximum number of extent records to return. If it is
899 "undef", then IO::AIO queries all extents of the file. As a very 1088 "undef", then IO::AIO queries all extents of the range. As a very
900 special case, if it is 0, then the callback receives the number of 1089 special case, if it is 0, then the callback receives the number of
901 extents instead of the extents themselves. 1090 extents instead of the extents themselves (which is unreliable, see
1091 below).
902 1092
903 If an error occurs, the callback receives no arguments. The special 1093 If an error occurs, the callback receives no arguments. The special
904 "errno" value "IO::AIO::EBADR" is available to test for flag errors. 1094 "errno" value "IO::AIO::EBADR" is available to test for flag errors.
905 1095
906 Otherwise, the callback receives an array reference with extent 1096 Otherwise, the callback receives an array reference with extent
… …
908 the following members: 1098 the following members:
909 1099
910 [$logical, $physical, $length, $flags] 1100 [$logical, $physical, $length, $flags]
911 1101
912 Flags is any combination of the following flag values (typically 1102 Flags is any combination of the following flag values (typically
913 either 0 or "IO::AIO::FIEMAP_EXTENT_LAST"): 1103 either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
914 1104
915 "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN", 1105 "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
916 "IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED", 1106 "IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",
917 "IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED", 1107 "IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
918 "IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED", 1108 "IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
919 "IO::AIO::FIEMAP_EXTENT_DATA_INLINE", 1109 "IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
920 "IO::AIO::FIEMAP_EXTENT_DATA_TAIL", 1110 "IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
921 "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED" 1111 "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
922 or "IO::AIO::FIEMAP_EXTENT_SHARED". 1112 or "IO::AIO::FIEMAP_EXTENT_SHARED".
923 1113
1114 At the time of this writing (Linux 3.2), this request is unreliable
1115 unless $count is "undef", as the kernel has all sorts of bugs
1116 preventing it to return all extents of a range for files with a
1117 large number of extents. The code (only) works around all these
1118 issues if $count is "undef".
1119
924 aio_group $callback->(...) 1120 aio_group $callback->(...)
925 This is a very special aio request: Instead of doing something, it 1121 This is a very special aio request: Instead of doing something, it
926 is a container for other aio requests, which is useful if you want 1122 is a container for other aio requests, which is useful if you want
927 to bundle many requests into a single, composite, request with a 1123 to bundle many requests into a single, composite, request with a
928 definite callback and the ability to cancel the whole request with 1124 definite callback and the ability to cancel the whole request with
… …
1007 aio_stat [$etcdir, "passwd"], sub { 1203 aio_stat [$etcdir, "passwd"], sub {
1008 # yay 1204 # yay
1009 }; 1205 };
1010 }; 1206 };
1011 1207
1012 That "aio_wd" is a request and not a normal function shows that creating 1208 The fact that "aio_wd" is a request and not a normal function shows that
1013 an IO::AIO::WD object is itself a potentially blocking operation, which 1209 creating an IO::AIO::WD object is itself a potentially blocking
1014 is why it is done asynchronously. 1210 operation, which is why it is done asynchronously.
1015 1211
1016 To stat the directory obtained with "aio_wd" above, one could write 1212 To stat the directory obtained with "aio_wd" above, one could write
1017 either of the following three request calls: 1213 either of the following three request calls:
1018 1214
1019 aio_lstat "/etc" , sub { ... # pathname as normal string 1215 aio_lstat "/etc" , sub { ... # pathname as normal string
… …
1036 There are some caveats: when directories get renamed (or deleted), the 1232 There are some caveats: when directories get renamed (or deleted), the
1037 pathname string doesn't change, so will point to the new directory (or 1233 pathname string doesn't change, so will point to the new directory (or
1038 nowhere at all), while the directory fd, if available on the system, 1234 nowhere at all), while the directory fd, if available on the system,
1039 will still point to the original directory. Most functions accepting a 1235 will still point to the original directory. Most functions accepting a
1040 pathname will use the directory fd on newer systems, and the string on 1236 pathname will use the directory fd on newer systems, and the string on
1041 older systems. Some functions (such as realpath) will always rely on the 1237 older systems. Some functions (such as "aio_realpath") will always rely
1042 string form of the pathname. 1238 on the string form of the pathname.
1043 1239
1044 So this fucntionality is mainly useful to get some protection against 1240 So this functionality is mainly useful to get some protection against
1045 "chdir", to easily get an absolute path out of a relative path for 1241 "chdir", to easily get an absolute path out of a relative path for
1046 future reference, and to speed up doing many operations in the same 1242 future reference, and to speed up doing many operations in the same
1047 directory (e.g. when stat'ing all files in a directory). 1243 directory (e.g. when stat'ing all files in a directory).
1048 1244
1049 The following functions implement this working directory abstraction: 1245 The following functions implement this working directory abstraction:
… …
1059 Since passing "undef" as working directory component of a pathname 1255 Since passing "undef" as working directory component of a pathname
1060 fails the request with "ENOENT", there is often no need for error 1256 fails the request with "ENOENT", there is often no need for error
1061 checking in the "aio_wd" callback, as future requests using the 1257 checking in the "aio_wd" callback, as future requests using the
1062 value will fail in the expected way. 1258 value will fail in the expected way.
1063 1259
1064 If this call isn't available because your OS lacks it or it couldn't
1065 be detected, it will be emulated by calling "fsync" instead.
1066
1067 IO::AIO::CWD 1260 IO::AIO::CWD
1068 This is a compiletime constant (object) that represents the process 1261 This is a compile time constant (object) that represents the process
1069 current working directory. 1262 current working directory.
1070 1263
1071 Specifying this object as working directory object for a pathname is 1264 Specifying this object as working directory object for a pathname is
1072 as if the pathname would be specified directly, without a directory 1265 as if the pathname would be specified directly, without a directory
1073 object, e.g., these calls are functionally identical: 1266 object. For example, these calls are functionally identical:
1074 1267
1075 aio_stat "somefile", sub { ... }; 1268 aio_stat "somefile", sub { ... };
1076 aio_stat [IO::AIO::CWD, "somefile"], sub { ... }; 1269 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1270
1271 To recover the path associated with an IO::AIO::WD object, you can use
1272 "aio_realpath":
1273
1274 aio_realpath $wd, sub {
1275 warn "path is $_[0]\n";
1276 };
1277
1278 Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir"
1279 sometimes, fall back to using an absolue path.
1077 1280
1078 IO::AIO::REQ CLASS 1281 IO::AIO::REQ CLASS
1079 All non-aggregate "aio_*" functions return an object of this class when 1282 All non-aggregate "aio_*" functions return an object of this class when
1080 called in non-void context. 1283 called in non-void context.
1081 1284
… …
1233 results. 1436 results.
1234 1437
1235 See "poll_cb" for an example. 1438 See "poll_cb" for an example.
1236 1439
1237 IO::AIO::poll_cb 1440 IO::AIO::poll_cb
1238 Process some outstanding events on the result pipe. You have to call 1441 Process some requests that have reached the result phase (i.e. they
1442 have been executed but the results are not yet reported). You have
1443 to call this "regularly" to finish outstanding requests.
1444
1239 this regularly. Returns 0 if all events could be processed (or there 1445 Returns 0 if all events could be processed (or there were no events
1240 were no events to process), or -1 if it returned earlier for 1446 to process), or -1 if it returned earlier for whatever reason.
1241 whatever reason. Returns immediately when no events are outstanding. 1447 Returns immediately when no events are outstanding. The amount of
1242 The amount of events processed depends on the settings of 1448 events processed depends on the settings of "IO::AIO::max_poll_req",
1243 "IO::AIO::max_poll_req" and "IO::AIO::max_poll_time". 1449 "IO::AIO::max_poll_time" and "IO::AIO::max_outstanding".
1244 1450
1245 If not all requests were processed for whatever reason, the 1451 If not all requests were processed for whatever reason, the poll
1246 filehandle will still be ready when "poll_cb" returns, so normally 1452 file descriptor will still be ready when "poll_cb" returns, so
1247 you don't have to do anything special to have it called later. 1453 normally you don't have to do anything special to have it called
1454 later.
1248 1455
1249 Apart from calling "IO::AIO::poll_cb" when the event filehandle 1456 Apart from calling "IO::AIO::poll_cb" when the event filehandle
1250 becomes ready, it can be beneficial to call this function from loops 1457 becomes ready, it can be beneficial to call this function from loops
1251 which submit a lot of requests, to make sure the results get 1458 which submit a lot of requests, to make sure the results get
1252 processed when they become available and not just when the loop is 1459 processed when they become available and not just when the loop is
… …
1260 Event->io (fd => IO::AIO::poll_fileno, 1467 Event->io (fd => IO::AIO::poll_fileno,
1261 poll => 'r', async => 1, 1468 poll => 'r', async => 1,
1262 cb => \&IO::AIO::poll_cb); 1469 cb => \&IO::AIO::poll_cb);
1263 1470
1264 IO::AIO::poll_wait 1471 IO::AIO::poll_wait
1265 If there are any outstanding requests and none of them in the result 1472 Wait until either at least one request is in the result phase or no
1266 phase, wait till the result filehandle becomes ready for reading 1473 requests are outstanding anymore.
1267 (simply does a "select" on the filehandle. This is useful if you 1474
1268 want to synchronously wait for some requests to finish). 1475 This is useful if you want to synchronously wait for some requests
1476 to become ready, without actually handling them.
1269 1477
1270 See "nreqs" for an example. 1478 See "nreqs" for an example.
1271 1479
1272 IO::AIO::poll 1480 IO::AIO::poll
1273 Waits until some requests have been handled. 1481 Waits until some requests have been handled.
… …
1282 1490
1283 Strictly equivalent to: 1491 Strictly equivalent to:
1284 1492
1285 IO::AIO::poll_wait, IO::AIO::poll_cb 1493 IO::AIO::poll_wait, IO::AIO::poll_cb
1286 while IO::AIO::nreqs; 1494 while IO::AIO::nreqs;
1495
1496 This function can be useful at program aborts, to make sure
1497 outstanding I/O has been done ("IO::AIO" uses an "END" block which
1498 already calls this function on normal exits), or when you are merely
1499 using "IO::AIO" for its more advanced functions, rather than for
1500 async I/O, e.g.:
1501
1502 my ($dirs, $nondirs);
1503 IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1504 IO::AIO::flush;
1505 # $dirs, $nondirs are now set
1287 1506
1288 IO::AIO::max_poll_reqs $nreqs 1507 IO::AIO::max_poll_reqs $nreqs
1289 IO::AIO::max_poll_time $seconds 1508 IO::AIO::max_poll_time $seconds
1290 These set the maximum number of requests (default 0, meaning 1509 These set the maximum number of requests (default 0, meaning
1291 infinity) that are being processed by "IO::AIO::poll_cb" in one 1510 infinity) that are being processed by "IO::AIO::poll_cb" in one
… …
1381 no longer exceeded. 1600 no longer exceeded.
1382 1601
1383 In other words, this setting does not enforce a queue limit, but can 1602 In other words, this setting does not enforce a queue limit, but can
1384 be used to make poll functions block if the limit is exceeded. 1603 be used to make poll functions block if the limit is exceeded.
1385 1604
1386 This is a very bad function to use in interactive programs because 1605 This is a bad function to use in interactive programs because it
1387 it blocks, and a bad way to reduce concurrency because it is 1606 blocks, and a bad way to reduce concurrency because it is inexact.
1388 inexact: Better use an "aio_group" together with a feed callback. 1607 If you need to issue many requests without being able to call a poll
1608 function on demand, it is better to use an "aio_group" together with
1609 a feed callback.
1389 1610
1390 It's main use is in scripts without an event loop - when you want to 1611 Its main use is in scripts without an event loop - when you want to
1391 stat a lot of files, you can write somehting like this: 1612 stat a lot of files, you can write something like this:
1392 1613
1393 IO::AIO::max_outstanding 32; 1614 IO::AIO::max_outstanding 32;
1394 1615
1395 for my $path (...) { 1616 for my $path (...) {
1396 aio_stat $path , ...; 1617 aio_stat $path , ...;
… …
1398 } 1619 }
1399 1620
1400 IO::AIO::flush; 1621 IO::AIO::flush;
1401 1622
1402 The call to "poll_cb" inside the loop will normally return 1623 The call to "poll_cb" inside the loop will normally return
1403 instantly, but as soon as more thna 32 reqeusts are in-flight, it 1624 instantly, allowing the loop to progress, but as soon as more than
1404 will block until some requests have been handled. This keeps the 1625 32 requests are in-flight, it will block until some requests have
1405 loop from pushing a large number of "aio_stat" requests onto the 1626 been handled. This keeps the loop from pushing a large number of
1406 queue. 1627 "aio_stat" requests onto the queue (which, with many paths to stat,
1628 can use up a lot of memory).
1407 1629
1408 The default value for "max_outstanding" is very large, so there is 1630 The default value for "max_outstanding" is very large, so there is
1409 no practical limit on the number of outstanding requests. 1631 no practical limit on the number of outstanding requests.
1410 1632
1411 STATISTICAL INFORMATION 1633 STATISTICAL INFORMATION
… …
1425 1647
1426 IO::AIO::npending 1648 IO::AIO::npending
1427 Returns the number of requests currently in the pending state 1649 Returns the number of requests currently in the pending state
1428 (executed, but not yet processed by poll_cb). 1650 (executed, but not yet processed by poll_cb).
1429 1651
1652 SUBSECOND STAT TIME ACCESS
1653 Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
1654 generally find access/modification and change times with subsecond time
1655 accuracy of the system supports it, but perl's built-in functions only
1656 return the integer part.
1657
1658 The following functions return the timestamps of the most recent stat
1659 with subsecond precision on most systems and work both after
1660 "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
1661 value is only meaningful after a successful "stat"/"lstat" call, or
1662 during/after a successful "aio_stat"/"aio_lstat" callback.
1663
1664 This is similar to the Time::HiRes "stat" functions, but can return full
1665 resolution without rounding and work with standard perl "stat",
1666 alleviating the need to call the special "Time::HiRes" functions, which
1667 do not act like their perl counterparts.
1668
1669 On operating systems or file systems where subsecond time resolution is
1670 not supported or could not be detected, a fractional part of 0 is
1671 returned, so it is always safe to call these functions.
1672
1673 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
1674 IO::AIO::st_btime
1675 Return the access, modication, change or birth time, respectively,
1676 including fractional part. Due to the limited precision of floating
1677 point, the accuracy on most platforms is only a bit better than
1678 milliseconds for times around now - see the *nsec* function family,
1679 below, for full accuracy.
1680
1681 File birth time is only available when the OS and perl support it
1682 (on FreeBSD and NetBSD at the time of this writing, although support
1683 is adaptive, so if your OS/perl gains support, IO::AIO can take
1684 advantage of it). On systems where it isn't available, 0 is
1685 currently returned, but this might change to "undef" in a future
1686 version.
1687
1688 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1689 Returns access, modification, change and birth time all in one go,
1690 and maybe more times in the future version.
1691
1692 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
1693 IO::AIO::st_ctimensec, IO::AIO::st_btimensec
1694 Return the fractional access, modifcation, change or birth time, in
1695 nanoseconds, as an integer in the range 0 to 999999999.
1696
1697 Note that no accessors are provided for access, modification and
1698 change times - you need to get those from "stat _" if required ("int
1699 IO::AIO::st_atime" and so on will *not* generally give you the
1700 correct value).
1701
1702 $seconds = IO::AIO::st_btimesec
1703 The (integral) seconds part of the file birth time, if available.
1704
1705 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1706 Like the functions above, but returns all four times in one go (and
1707 maybe more in future versions).
1708
1709 $counter = IO::AIO::st_gen
1710 Returns the generation counter (in practice this is just a random
1711 number) of the file. This is only available on platforms which have
1712 this member in their "struct stat" (most BSDs at the time of this
1713 writing) and generally only to the root usert. If unsupported, 0 is
1714 returned, but this might change to "undef" in a future version.
1715
1716 Example: print the high resolution modification time of /etc, using
1717 "stat", and "IO::AIO::aio_stat".
1718
1719 if (stat "/etc") {
1720 printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
1721 }
1722
1723 IO::AIO::aio_stat "/etc", sub {
1724 $_[0]
1725 and return;
1726
1727 printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
1728 };
1729
1730 IO::AIO::flush;
1731
1732 Output of the awbove on my system, showing reduced and full accuracy:
1733
1734 stat(/etc) mtime: 1534043702.020808
1735 aio_stat(/etc) mtime: 1534043702.020807792
1736
1430 MISCELLANEOUS FUNCTIONS 1737 MISCELLANEOUS FUNCTIONS
1431 IO::AIO implements some functions that might be useful, but are not 1738 IO::AIO implements some functions that are useful when you want to use
1432 asynchronous. 1739 some "Advanced I/O" function not available to in Perl, without going the
1740 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1741 counterpart.
1742
1743 $retval = IO::AIO::fexecve $fh, $argv, $envp
1744 A more-or-less direct equivalent to the POSIX "fexecve" functions,
1745 which allows you to specify the program to be executed via a file
1746 descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not
1747 available.
1748
1749 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
1750 undef
1751 Calls the GNU/Linux mount syscall with the given arguments. All
1752 except $flags are strings, and if $data is "undef", a "NULL" will be
1753 passed.
1754
1755 The following values for $flags are available:
1756
1757 "IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
1758 "IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
1759 "IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
1760 "IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
1761 "IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
1762 "IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
1763 "IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
1764 "IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
1765 "IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
1766 "IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
1767 "IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
1768 "IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
1769
1770 $retval = IO::AIO::umount $path, $flags = 0
1771 Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
1772 "umount" if $flags is 0, otherwqise always tries to call "umount2".
1773
1774 The following $flags are available:
1775
1776 "IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
1777 and "IO::AIO::UMOUNT_NOFOLLOW".
1778
1779 $numfd = IO::AIO::get_fdlimit
1780 Tries to find the current file descriptor limit and returns it, or
1781 "undef" and sets $! in case of an error. The limit is one larger
1782 than the highest valid file descriptor number.
1783
1784 IO::AIO::min_fdlimit [$numfd]
1785 Try to increase the current file descriptor limit(s) to at least
1786 $numfd by changing the soft or hard file descriptor resource limit.
1787 If $numfd is missing, it will try to set a very high limit, although
1788 this is not recommended when you know the actual minimum that you
1789 require.
1790
1791 If the limit cannot be raised enough, the function makes a
1792 best-effort attempt to increase the limit as much as possible, using
1793 various tricks, while still failing. You can query the resulting
1794 limit using "IO::AIO::get_fdlimit".
1795
1796 If an error occurs, returns "undef" and sets $!, otherwise returns
1797 true.
1433 1798
1434 IO::AIO::sendfile $ofh, $ifh, $offset, $count 1799 IO::AIO::sendfile $ofh, $ifh, $offset, $count
1435 Calls the "eio_sendfile_sync" function, which is like 1800 Calls the "eio_sendfile_sync" function, which is like
1436 "aio_sendfile", but is blocking (this makes most sense if you know 1801 "aio_sendfile", but is blocking (this makes most sense if you know
1437 the input data is likely cached already and the output filehandle is 1802 the input data is likely cached already and the output filehandle is
… …
1454 details). The following advice constants are available: 1819 details). The following advice constants are available:
1455 "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL", 1820 "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1456 "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED", 1821 "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1457 "IO::AIO::MADV_DONTNEED". 1822 "IO::AIO::MADV_DONTNEED".
1458 1823
1824 If $offset is negative, counts from the end. If $length is negative,
1825 the remaining length of the $scalar is used. If possible, $length
1826 will be reduced to fit into the $scalar.
1827
1459 On systems that do not implement "posix_madvise", this function 1828 On systems that do not implement "posix_madvise", this function
1460 returns ENOSYS, otherwise the return value of "posix_madvise". 1829 returns ENOSYS, otherwise the return value of "posix_madvise".
1461 1830
1462 IO::AIO::mprotect $scalar, $offset, $len, $protect 1831 IO::AIO::mprotect $scalar, $offset, $len, $protect
1463 Simply calls the "mprotect" function on the preferably AIO::mmap'ed 1832 Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1464 $scalar (see its manpage for details). The following protect 1833 $scalar (see its manpage for details). The following protect
1465 constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ", 1834 constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
1466 "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC". 1835 "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1467 1836
1837 If $offset is negative, counts from the end. If $length is negative,
1838 the remaining length of the $scalar is used. If possible, $length
1839 will be reduced to fit into the $scalar.
1840
1468 On systems that do not implement "mprotect", this function returns 1841 On systems that do not implement "mprotect", this function returns
1469 ENOSYS, otherwise the return value of "mprotect". 1842 ENOSYS, otherwise the return value of "mprotect".
1470 1843
1471 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 1844 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1472 Memory-maps a file (or anonymous memory range) and attaches it to 1845 Memory-maps a file (or anonymous memory range) and attaches it to
1473 the given $scalar, which will act like a string scalar. 1846 the given $scalar, which will act like a string scalar. Returns true
1847 on success, and false otherwise.
1474 1848
1849 The scalar must exist, but its contents do not matter - this means
1850 you cannot use a nonexistant array or hash element. When in doubt,
1851 "undef" the scalar first.
1852
1475 The only operations allowed on the scalar are "substr"/"vec" that 1853 The only operations allowed on the mmapped scalar are
1476 don't change the string length, and most read-only operations such 1854 "substr"/"vec", which don't change the string length, and most
1477 as copying it or searching it with regexes and so on. 1855 read-only operations such as copying it or searching it with regexes
1856 and so on.
1478 1857
1479 Anything else is unsafe and will, at best, result in memory leaks. 1858 Anything else is unsafe and will, at best, result in memory leaks.
1480 1859
1481 The memory map associated with the $scalar is automatically removed 1860 The memory map associated with the $scalar is automatically removed
1482 when the $scalar is destroyed, or when the "IO::AIO::mmap" or 1861 when the $scalar is undef'd or destroyed, or when the
1483 "IO::AIO::munmap" functions are called. 1862 "IO::AIO::mmap" or "IO::AIO::munmap" functions are called on it.
1484 1863
1485 This calls the "mmap"(2) function internally. See your system's 1864 This calls the "mmap"(2) function internally. See your system's
1486 manual page for details on the $length, $prot and $flags parameters. 1865 manual page for details on the $length, $prot and $flags parameters.
1487 1866
1488 The $length must be larger than zero and smaller than the actual 1867 The $length must be larger than zero and smaller than the actual
… …
1492 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or 1871 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1493 "IO::AIO::PROT_WRITE", 1872 "IO::AIO::PROT_WRITE",
1494 1873
1495 $flags can be a combination of "IO::AIO::MAP_SHARED" or 1874 $flags can be a combination of "IO::AIO::MAP_SHARED" or
1496 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when 1875 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1497 not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS" 1876 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1498 (which is set to "MAP_ANON" if your system only provides this 1877 "MAP_ANON" if your system only provides this constant),
1878 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1499 constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED", 1879 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1500 "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or 1880 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1501 "IO::AIO::MAP_NONBLOCK" 1881 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1882 "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1883 "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1502 1884
1503 If $fh is "undef", then a file descriptor of -1 is passed. 1885 If $fh is "undef", then a file descriptor of -1 is passed.
1504 1886
1505 $offset is the offset from the start of the file - it generally must 1887 $offset is the offset from the start of the file - it generally must
1506 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. 1888 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1518 1900
1519 my $fast_md5 = md5 $data; 1901 my $fast_md5 = md5 $data;
1520 1902
1521 IO::AIO::munmap $scalar 1903 IO::AIO::munmap $scalar
1522 Removes a previous mmap and undefines the $scalar. 1904 Removes a previous mmap and undefines the $scalar.
1905
1906 IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
1907 $new_address = 0]
1908 Calls the Linux-specific mremap(2) system call. The $scalar must
1909 have been mapped by "IO::AIO::mmap", and $flags must currently
1910 either be 0 or "IO::AIO::MREMAP_MAYMOVE".
1911
1912 Returns true if successful, and false otherwise. If the underlying
1913 mmapped region has changed address, then the true value has the
1914 numerical value 1, otherwise it has the numerical value 0:
1915
1916 my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
1917 or die "mremap: $!";
1918
1919 if ($success*1) {
1920 warn "scalar has chanegd address in memory\n";
1921 }
1922
1923 "IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
1924 implemented, but not supported and might go away in a future
1925 version.
1926
1927 On systems where this call is not supported or is not emulated, this
1928 call returns falls and sets $! to "ENOSYS".
1929
1930 IO::AIO::mlockall $flags
1931 Calls the "eio_mlockall_sync" function, which is like
1932 "aio_mlockall", but is blocking.
1523 1933
1524 IO::AIO::munlock $scalar, $offset = 0, $length = undef 1934 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1525 Calls the "munlock" function, undoing the effects of a previous 1935 Calls the "munlock" function, undoing the effects of a previous
1526 "aio_mlock" call (see its description for details). 1936 "aio_mlock" call (see its description for details).
1527 1937
1528 IO::AIO::munlockall 1938 IO::AIO::munlockall
1529 Calls the "munlockall" function. 1939 Calls the "munlockall" function.
1530 1940
1531 On systems that do not implement "munlockall", this function returns 1941 On systems that do not implement "munlockall", this function returns
1532 ENOSYS, otherwise the return value of "munlockall". 1942 ENOSYS, otherwise the return value of "munlockall".
1943
1944 $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1945 Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1946 socket and return the new file handle on success, or sets $! and
1947 returns "undef" on error.
1948
1949 The remote name of the new socket will be stored in $sockaddr, which
1950 will be extended to allow for at least $sockaddr_maxlen octets. If
1951 the socket name does not fit into $sockaddr_maxlen octets, this is
1952 signaled by returning a longer string in $sockaddr, which might or
1953 might not be truncated.
1954
1955 To accept name-less sockets, use "undef" for $sockaddr and 0 for
1956 $sockaddr_maxlen.
1957
1958 The main reasons to use this syscall rather than portable accept(2)
1959 are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags
1960 and you can accept name-less sockets by specifying 0 for
1961 $sockaddr_maxlen, which is sadly not possible with perl's interface
1962 to "accept".
1963
1964 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1965 Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
1966 $w_off are "undef", then "NULL" is passed for these, otherwise they
1967 should be the file offset.
1968
1969 $r_fh and $w_fh should not refer to the same file, as splice might
1970 silently corrupt the data in this case.
1971
1972 The following symbol flag values are available:
1973 "IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
1974 "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
1975
1976 See the splice(2) manpage for details.
1977
1978 IO::AIO::tee $r_fh, $w_fh, $length, $flags
1979 Calls the GNU/Linux tee(2) syscall, see its manpage and the
1980 description for "IO::AIO::splice" above for details.
1981
1982 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
1983 Attempts to query or change the pipe buffer size. Obviously works
1984 only on pipes, and currently works only on GNU/Linux systems, and
1985 fails with -1/"ENOSYS" everywhere else. If anybody knows how to
1986 influence pipe buffer size on other systems, drop me a note.
1987
1988 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
1989 This is a direct interface to the Linux pipe2(2) system call. If
1990 $flags is missing or 0, then this should be the same as a call to
1991 perl's built-in "pipe" function and create a new pipe, and works on
1992 systems that lack the pipe2 syscall. On win32, this case invokes
1993 "_pipe (..., 4096, O_BINARY)".
1994
1995 If $flags is non-zero, it tries to invoke the pipe2 system call with
1996 the given flags (Linux 2.6.27, glibc 2.9).
1997
1998 On success, the read and write file handles are returned.
1999
2000 On error, nothing will be returned. If the pipe2 syscall is missing
2001 and $flags is non-zero, fails with "ENOSYS".
2002
2003 Please refer to pipe2(2) for more info on the $flags, but at the
2004 time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK"
2005 and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were
2006 supported.
2007
2008 Example: create a pipe race-free w.r.t. threads and fork:
2009
2010 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2011 or die "pipe2: $!\n";
2012
2013 $fh = IO::AIO::memfd_create $pathname[, $flags]
2014 This is a direct interface to the Linux memfd_create(2) system call.
2015 The (unhelpful) default for $flags is 0, but your default should be
2016 "IO::AIO::MFD_CLOEXEC".
2017
2018 On success, the new memfd filehandle is returned, otherwise returns
2019 "undef". If the memfd_create syscall is missing, fails with
2020 "ENOSYS".
2021
2022 Please refer to memfd_create(2) for more info on this call.
2023
2024 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
2025 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
2026 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
2027
2028 Example: create a new memfd.
2029
2030 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2031 or die "memfd_create: $!\n";
2032
2033 $fh = IO::AIO::pidfd_open $pid[, $flags]
2034 This is an interface to the Linux pidfd_open(2) system call. The
2035 default for $flags is 0.
2036
2037 On success, a new pidfd filehandle is returned (that is already set
2038 to close-on-exec), otherwise returns "undef". If the syscall is
2039 missing, fails with "ENOSYS".
2040
2041 Example: open pid 6341 as pidfd.
2042
2043 my $fh = IO::AIO::pidfd_open 6341
2044 or die "pidfd_open: $!\n";
2045
2046 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
2047 $flags]]
2048 This is an interface to the Linux pidfd_send_signal system call. The
2049 default for $siginfo is "undef" and the default for $flags is 0.
2050
2051 Returns the system call status. If the syscall is missing, fails
2052 with "ENOSYS".
2053
2054 When specified, $siginfo must be a reference to a hash with one or
2055 more of the following members:
2056
2057 code - the "si_code" member
2058 pid - the "si_pid" member
2059 uid - the "si_uid" member
2060 value_int - the "si_value.sival_int" member
2061 value_ptr - the "si_value.sival_ptr" member, specified as an integer
2062
2063 Example: send a SIGKILL to the specified process.
2064
2065 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2066 and die "pidfd_send_signal: $!\n";
2067
2068 Example: send a SIGKILL to the specified process with extra data.
2069
2070 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2071 and die "pidfd_send_signal: $!\n";
2072
2073 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2074 This is an interface to the Linux pidfd_getfd system call. The
2075 default for $flags is 0.
2076
2077 On success, returns a dup'ed copy of the target file descriptor
2078 (specified as an integer) returned (that is already set to
2079 close-on-exec), otherwise returns "undef". If the syscall is
2080 missing, fails with "ENOSYS".
2081
2082 Example: get a copy of standard error of another process and print
2083 soemthing to it.
2084
2085 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2086 or die "pidfd_getfd: $!\n";
2087 print $errfh "stderr\n";
2088
2089 $fh = IO::AIO::eventfd [$initval, [$flags]]
2090 This is a direct interface to the Linux eventfd(2) system call. The
2091 (unhelpful) defaults for $initval and $flags are 0 for both.
2092
2093 On success, the new eventfd filehandle is returned, otherwise
2094 returns "undef". If the eventfd syscall is missing, fails with
2095 "ENOSYS".
2096
2097 Please refer to eventfd(2) for more info on this call.
2098
2099 The following symbol flag values are available:
2100 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
2101 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
2102
2103 Example: create a new eventfd filehandle:
2104
2105 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
2106 or die "eventfd: $!\n";
2107
2108 $fh = IO::AIO::timerfd_create $clockid[, $flags]
2109 This is a direct interface to the Linux timerfd_create(2) system
2110 call. The (unhelpful) default for $flags is 0, but your default
2111 should be "IO::AIO::TFD_CLOEXEC".
2112
2113 On success, the new timerfd filehandle is returned, otherwise
2114 returns "undef". If the timerfd_create syscall is missing, fails
2115 with "ENOSYS".
2116
2117 Please refer to timerfd_create(2) for more info on this call.
2118
2119 The following $clockid values are available:
2120 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
2121 "IO::AIO::CLOCK_CLOCK_BOOTTIME" (Linux 3.15)
2122 "IO::AIO::CLOCK_CLOCK_REALTIME_ALARM" (Linux 3.11) and
2123 "IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM" (Linux 3.11).
2124
2125 The following $flags values are available (Linux 2.6.27):
2126 "IO::AIO::TFD_NONBLOCK" and "IO::AIO::TFD_CLOEXEC".
2127
2128 Example: create a new timerfd and set it to one-second repeated
2129 alarms, then wait for two alarms:
2130
2131 my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
2132 or die "timerfd_create: $!\n";
2133
2134 defined IO::AIO::timerfd_settime $fh, 0, 1, 1
2135 or die "timerfd_settime: $!\n";
2136
2137 for (1..2) {
2138 8 == sysread $fh, my $buf, 8
2139 or die "timerfd read failure\n";
2140
2141 printf "number of expirations (likely 1): %d\n",
2142 unpack "Q", $buf;
2143 }
2144
2145 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags,
2146 $new_interval, $nbw_value
2147 This is a direct interface to the Linux timerfd_settime(2) system
2148 call. Please refer to its manpage for more info on this call.
2149
2150 The new itimerspec is specified using two (possibly fractional)
2151 second values, $new_interval and $new_value).
2152
2153 On success, the current interval and value are returned (as per
2154 "timerfd_gettime"). On failure, the empty list is returned.
2155
2156 The following $flags values are available:
2157 "IO::AIO::TFD_TIMER_ABSTIME" and "IO::AIO::TFD_TIMER_CANCEL_ON_SET".
2158
2159 See "IO::AIO::timerfd_create" for a full example.
2160
2161 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
2162 This is a direct interface to the Linux timerfd_gettime(2) system
2163 call. Please refer to its manpage for more info on this call.
2164
2165 On success, returns the current values of interval and value for the
2166 given timerfd (as potentially fractional second values). On failure,
2167 the empty list is returned.
1533 2168
1534EVENT LOOP INTEGRATION 2169EVENT LOOP INTEGRATION
1535 It is recommended to use AnyEvent::AIO to integrate IO::AIO 2170 It is recommended to use AnyEvent::AIO to integrate IO::AIO
1536 automatically into many event loops: 2171 automatically into many event loops:
1537 2172
… …
1587 forking, if "IO::AIO" was used in the parent. Calling it while 2222 forking, if "IO::AIO" was used in the parent. Calling it while
1588 IO::AIO is active in the process will result in undefined behaviour. 2223 IO::AIO is active in the process will result in undefined behaviour.
1589 Calling it at any time will also result in any undefined (by POSIX) 2224 Calling it at any time will also result in any undefined (by POSIX)
1590 behaviour. 2225 behaviour.
1591 2226
2227 LINUX-SPECIFIC CALLS
2228 When a call is documented as "linux-specific" then this means it
2229 originated on GNU/Linux. "IO::AIO" will usually try to autodetect the
2230 availability and compatibility of such calls regardless of the platform
2231 it is compiled on, so platforms such as FreeBSD which often implement
2232 these calls will work. When in doubt, call them and see if they fail wth
2233 "ENOSYS".
2234
1592 MEMORY USAGE 2235 MEMORY USAGE
1593 Per-request usage: 2236 Per-request usage:
1594 2237
1595 Each aio request uses - depending on your architecture - around 100-200 2238 Each aio request uses - depending on your architecture - around 100-200
1596 bytes of memory. In addition, stat requests need a stat buffer (possibly 2239 bytes of memory. In addition, stat requests need a stat buffer (possibly
… …
1606 In the execution phase, some aio requests require more memory for 2249 In the execution phase, some aio requests require more memory for
1607 temporary buffers, and each thread requires a stack and other data 2250 temporary buffers, and each thread requires a stack and other data
1608 structures (usually around 16k-128k, depending on the OS). 2251 structures (usually around 16k-128k, depending on the OS).
1609 2252
1610KNOWN BUGS 2253KNOWN BUGS
1611 Known bugs will be fixed in the next release. 2254 Known bugs will be fixed in the next release :)
2255
2256KNOWN ISSUES
2257 Calls that try to "import" foreign memory areas (such as "IO::AIO::mmap"
2258 or "IO::AIO::aio_slurp") do not work with generic lvalues, such as
2259 non-created hash slots or other scalars I didn't think of. It's best to
2260 avoid such and either use scalar variables or making sure that the
2261 scalar exists (e.g. by storing "undef") and isn't "funny" (e.g. tied).
2262
2263 I am not sure anything can be done about this, so this is considered a
2264 known issue, rather than a bug.
1612 2265
1613SEE ALSO 2266SEE ALSO
1614 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a 2267 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
1615 more natural syntax. 2268 more natural syntax and IO::FDPass for file descriptor passing.
1616 2269
1617AUTHOR 2270AUTHOR
1618 Marc Lehmann <schmorp@schmorp.de> 2271 Marc Lehmann <schmorp@schmorp.de>
1619 http://home.schmorp.de/ 2272 http://home.schmorp.de/
1620 2273

Diff Legend

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