--- IO-AIO/README 2013/01/06 11:48:14 1.54 +++ IO-AIO/README 2016/01/18 11:53:09 1.57 @@ -66,7 +66,6 @@ This is a simple example that uses the EV module and loads /etc/passwd asynchronously: - use Fcntl; use EV; use IO::AIO; @@ -93,7 +92,7 @@ print $contents; # exit event loop and program - EV::unloop; + EV::break; }; }; @@ -101,7 +100,7 @@ # check for sockets etc. etc. # process events as long as there are some: - EV::loop; + EV::run; REQUEST ANATOMY AND LIFETIME Every "aio_*" function creates a request. which is a C data structure @@ -174,7 +173,7 @@ aio_link $srcpath, $dstpath, $callback->($status) aio_symlink $srcpath, $dstpath, $callback->($status) aio_readlink $pathname, $callback->($link) - aio_realpath $pathname, $callback->($link) + aio_realpath $pathname, $callback->($path) aio_rename $srcpath, $dstpath, $callback->($status) aio_mkdir $pathname, $mode, $callback->($status) aio_rmdir $pathname, $callback->($status) @@ -333,7 +332,8 @@ "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY", "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY", - "O_DSYNC", "O_RSYNC", "O_SYNC" and "O_TTY_INIT". + "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", and + "O_TTY_INIT". aio_close $fh, $callback->($status) Asynchronously close a file and call the callback with the result @@ -532,8 +532,8 @@ fsid => 1810 } - Here is a (likely partial) list of fsid values used by Linux - it is - safe to hardcode these when the $^O is "linux": + Here is a (likely partial - send me updates!) list of fsid values + used by Linux - it is safe to hardcode these when $^O is "linux": 0x0000adf5 adfs 0x0000adff affs @@ -556,8 +556,9 @@ 0x0000f15f ecryptfs 0x00414a53 efs 0x0000137d ext - 0x0000ef53 ext2/ext3 + 0x0000ef53 ext2/ext3/ext4 0x0000ef51 ext2 + 0xf2f52010 f2fs 0x00004006 fat 0x65735546 fuseblk 0x65735543 fusectl @@ -566,6 +567,7 @@ 0x47504653 gpfs 0x00004244 hfs 0xf995e849 hpfs + 0x00c0ffee hostfs 0x958458f6 hugetlbfs 0x2bad1dea inotifyfs 0x00009660 isofs @@ -590,6 +592,7 @@ 0x00009fa0 proc 0x6165676c pstorefs 0x0000002f qnx4 + 0x68191122 qnx6 0x858458f6 ramfs 0x52654973 reiserfs 0x00007275 romfs @@ -646,13 +649,17 @@ Works like truncate(2) or ftruncate(2). aio_allocate $fh, $mode, $offset, $len, $callback->($status) - Allocates or freed disk space according to the $mode argument. See - the linux "fallocate" docuemntation for details. + Allocates or frees disk space according to the $mode argument. See + the linux "fallocate" documentation for details. - $mode can currently be 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to - allocate space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE | + $mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate + space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range. + IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range + (without leaving a hole) and "FALLOC_FL_ZERO_RANGE", to zero a range + (see your fallocate(2) manpage). + The file system block size used by "fallocate" is presumably the "f_bsize" returned by "statvfs". @@ -1131,9 +1138,9 @@ }; }; - That "aio_wd" is a request and not a normal function shows that creating - an IO::AIO::WD object is itself a potentially blocking operation, which - is why it is done asynchronously. + The fact that "aio_wd" is a request and not a normal function shows that + creating an IO::AIO::WD object is itself a potentially blocking + operation, which is why it is done asynchronously. To stat the directory obtained with "aio_wd" above, one could write either of the following three request calls: @@ -1183,9 +1190,6 @@ checking in the "aio_wd" callback, as future requests using the value will fail in the expected way. - If this call isn't available because your OS lacks it or it couldn't - be detected, it will be emulated by calling "fsync" instead. - IO::AIO::CWD This is a compiletime constant (object) that represents the process current working directory. @@ -1524,7 +1528,7 @@ it blocks, and a bad way to reduce concurrency because it is inexact: Better use an "aio_group" together with a feed callback. - It's main use is in scripts without an event loop - when you want to + Its main use is in scripts without an event loop - when you want to stat a lot of files, you can write somehting like this: IO::AIO::max_outstanding 32; @@ -1565,8 +1569,10 @@ (executed, but not yet processed by poll_cb). MISCELLANEOUS FUNCTIONS - IO::AIO implements some functions that might be useful, but are not - asynchronous. + IO::AIO implements some functions that are useful when you want to use + some "Advanced I/O" function not available to in Perl, without going the + "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" + counterpart. IO::AIO::sendfile $ofh, $ifh, $offset, $count Calls the "eio_sendfile_sync" function, which is like @@ -1632,11 +1638,13 @@ $flags can be a combination of "IO::AIO::MAP_SHARED" or "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when - not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS" - (which is set to "MAP_ANON" if your system only provides this - constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED", - "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or - "IO::AIO::MAP_NONBLOCK" + not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to + "MAP_ANON" if your system only provides this constant), + "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED", + "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE", + "IO::AIO::MAP_NONBLOCK", "IO::AIO::MAP_FIXED", + "IO::AIO::MAP_GROWSDOWN", "IO::AIO::MAP_32BIT", + "IO::AIO::MAP_HUGETLB" or "IO::AIO::MAP_STACK". If $fh is "undef", then a file descriptor of -1 is passed. @@ -1684,9 +1692,35 @@ See the splice(2) manpage for details. IO::AIO::tee $r_fh, $w_fh, $length, $flags - Calls the GNU/Linux tee(2) syscall, see it's manpage and the + Calls the GNU/Linux tee(2) syscall, see its manpage and the description for "IO::AIO::splice" above for details. + $actual_size = IO::AIO::pipesize $r_fh[, $new_size] + Attempts to query or change the pipe buffer size. Obviously works + only on pipes, and currently works only on GNU/Linux systems, and + fails with -1/"ENOSYS" everywhere else. If anybody knows how to + influence pipe buffer size on other systems, drop me a note. + + ($rfh, $wfh) = IO::AIO::pipe2 [$flags] + This is a direct interface to the Linux pipe2(2) system call. If + $flags is missing or 0, then this should be the same as a call to + perl's built-in "pipe" function and create a new pipe, and works on + systems that lack the pipe2 syscall. On win32, this case invokes + "_pipe (..., 4096, O_BINARY)". + + If $flags is non-zero, it tries to invoke the pipe2 system call with + the given flags (Linux 2.6.27, glibc 2.9). + + On success, the read and write file handles are returned. + + On error, nothing will be returned. If the pipe2 syscall is missing + and $flags is non-zero, fails with "ENOSYS". + + Please refer to pipe2(2) for more info on the $flags, but at the + time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK" + and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were + supported. + EVENT LOOP INTEGRATION It is recommended to use AnyEvent::AIO to integrate IO::AIO automatically into many event loops: