--- IO-AIO/README 2012/10/11 03:20:52 1.53 +++ 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". @@ -694,7 +701,7 @@ aio_realpath $pathname, $callback->($path) Asynchronously make the path absolute and resolve any symlinks in - $path. The resulting path only consists of directories (Same as + $path. The resulting path only consists of directories (same as Cwd::realpath). This request can be used to get the absolute path of the current @@ -704,6 +711,10 @@ Asynchronously rename the object at $srcpath to $dstpath, just as rename(2) and call the callback with the result code. + On systems that support the AIO::WD working directory abstraction + natively, the case "[$wd, "."]" as $srcpath is specialcased - + instead of failing, "rename" is called on the absolute path of $wd. + aio_mkdir $pathname, $mode, $callback->($status) Asynchronously mkdir (create) a directory and call the callback with the result code. $mode will be modified by the umask at the time the @@ -713,6 +724,10 @@ Asynchronously rmdir (delete) a directory and call the callback with the result code. + On systems that support the AIO::WD working directory abstraction + natively, the case "[$wd, "."]" is specialcased - instead of + failing, "rmdir" is called on the absolute path of $wd. + aio_readdir $pathname, $callback->($entries) Unlike the POSIX call of the same name, "aio_readdir" reads an entire directory (i.e. opendir + readdir + closedir). The entries @@ -944,7 +959,7 @@ inside the scalar. All caveats and parameters are the same as for "aio_msync", above, except for flags, which must be either 0 (which reads all pages and ensures they are instantiated) or - "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading + "IO::AIO::MT_MODIFY", which modifies the memory pages (by reading and writing an octet from it, which dirties the page). aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) @@ -1123,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: @@ -1155,7 +1170,7 @@ older systems. Some functions (such as realpath) will always rely on the string form of the pathname. - So this fucntionality is mainly useful to get some protection against + So this functionality is mainly useful to get some protection against "chdir", to easily get an absolute path out of a relative path for future reference, and to speed up doing many operations in the same directory (e.g. when stat'ing all files in a directory). @@ -1175,20 +1190,27 @@ 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. Specifying this object as working directory object for a pathname is as if the pathname would be specified directly, without a directory - object, e.g., these calls are functionally identical: + object. For example, these calls are functionally identical: aio_stat "somefile", sub { ... }; aio_stat [IO::AIO::CWD, "somefile"], sub { ... }; + To recover the path associated with an IO::AIO::WD object, you can use + "aio_realpath": + + aio_realpath $wd, sub { + warn "path is $_[0]\n"; + }; + + Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir" + sometimes, fall back to using an absolue path. + IO::AIO::REQ CLASS All non-aggregate "aio_*" functions return an object of this class when called in non-void context. @@ -1349,16 +1371,20 @@ See "poll_cb" for an example. IO::AIO::poll_cb - Process some outstanding events on the result pipe. You have to call - this regularly. Returns 0 if all events could be processed (or there - were no events to process), or -1 if it returned earlier for - whatever reason. Returns immediately when no events are outstanding. - The amount of events processed depends on the settings of - "IO::AIO::max_poll_req" and "IO::AIO::max_poll_time". - - If not all requests were processed for whatever reason, the - filehandle will still be ready when "poll_cb" returns, so normally - you don't have to do anything special to have it called later. + Process some requests that have reached the result phase (i.e. they + have been executed but the results are not yet reported). You have + to call this "regularly" to finish outstanding requests. + + Returns 0 if all events could be processed (or there were no events + to process), or -1 if it returned earlier for whatever reason. + Returns immediately when no events are outstanding. The amount of + events processed depends on the settings of "IO::AIO::max_poll_req", + "IO::AIO::max_poll_time" and "IO::AIO::max_outstanding". + + If not all requests were processed for whatever reason, the poll + file descriptor will still be ready when "poll_cb" returns, so + normally you don't have to do anything special to have it called + later. Apart from calling "IO::AIO::poll_cb" when the event filehandle becomes ready, it can be beneficial to call this function from loops @@ -1376,10 +1402,11 @@ cb => \&IO::AIO::poll_cb); IO::AIO::poll_wait - If there are any outstanding requests and none of them in the result - phase, wait till the result filehandle becomes ready for reading - (simply does a "select" on the filehandle. This is useful if you - want to synchronously wait for some requests to finish). + Wait until either at least one request is in the result phase or no + requests are outstanding anymore. + + This is useful if you want to synchronously wait for some requests + to become ready, without actually handling them. See "nreqs" for an example. @@ -1501,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; @@ -1542,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 @@ -1609,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. @@ -1661,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: