--- IO-AIO/README 2011/10/09 08:24:49 1.50 +++ IO-AIO/README 2012/10/11 03:20:52 1.53 @@ -148,13 +148,14 @@ FUNCTIONS QUICK OVERVIEW - This section simply lists the prototypes of the most important functions - for quick reference. See the following sections for function-by-function + This section simply lists the prototypes most of the functions for quick + reference. See the following sections for function-by-function documentation. aio_wd $pathname, $callback->($wd) aio_open $pathname, $flags, $mode, $callback->($fh) aio_close $fh, $callback->($status) + aio_seek $fh,$offset,$whence, $callback->($offs) aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) @@ -164,8 +165,10 @@ aio_statvfs $fh_or_path, $callback->($statvfs) aio_utime $fh_or_path, $atime, $mtime, $callback->($status) aio_chown $fh_or_path, $uid, $gid, $callback->($status) - aio_truncate $fh_or_path, $offset, $callback->($status) aio_chmod $fh_or_path, $mode, $callback->($status) + aio_truncate $fh_or_path, $offset, $callback->($status) + aio_allocate $fh, $mode, $offset, $len, $callback->($status) + aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents) aio_unlink $pathname, $callback->($status) aio_mknod $pathname, $mode, $dev, $callback->($status) aio_link $srcpath, $dstpath, $callback->($status) @@ -217,12 +220,14 @@ IO::AIO::sendfile $ofh, $ifh, $offset, $count IO::AIO::fadvise $fh, $offset, $len, $advice + IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] + IO::AIO::munmap $scalar IO::AIO::madvise $scalar, $offset, $length, $advice IO::AIO::mprotect $scalar, $offset, $length, $protect IO::AIO::munlock $scalar, $offset = 0, $length = undef IO::AIO::munlockall - AIO REQUEST FUNCTIONS + API NOTES All the "aio_*" calls are more or less thin wrappers around the syscall with the same name (sans "aio_"). The arguments are similar or identical, and they all accept an additional (and optional) $callback @@ -262,6 +267,7 @@ This works, btw. independent of the internal UTF-8 bit, which IO::AIO handles correctly whether it is set or not. + AIO REQUEST FUNCTIONS $prev_pri = aioreq_pri [$pri] Returns the priority value that would be used for the next request and, if $pri is given, sets the priority for the next aio request. @@ -293,7 +299,8 @@ aio_open $pathname, $flags, $mode, $callback->($fh) Asynchronously open or create a file and call the callback with a - newly created filehandle for the file. + newly created filehandle for the file (or "undef" in case of an + error). The pathname passed to "aio_open" must be absolute. See API NOTES, above, for an explanation. @@ -343,6 +350,25 @@ Or in other words: the file descriptor will be closed, but it will not be free for reuse until the perl filehandle is closed. + aio_seek $fh, $offset, $whence, $callback->($offs) + Seeks the filehandle to the new $offset, similarly to perl's + "sysseek". The $whence can use the traditional values (0 for + "IO::AIO::SEEK_SET", 1 for "IO::AIO::SEEK_CUR" or 2 for + "IO::AIO::SEEK_END"). + + The resulting absolute offset will be passed to the callback, or -1 + in case of an error. + + In theory, the $whence constants could be different than the + corresponding values from Fcntl, but perl guarantees they are the + same, so don't panic. + + As a GNU/Linux (and maybe Solaris) extension, also the constants + "IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if they + could be found. No guarantees about suitability for use in + "aio_seek" or Perl's "sysseek" can be made though, although I would + naively assume they "just work". + aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) Reads or writes $length bytes from or to the specified $fh and @@ -506,6 +532,88 @@ 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": + + 0x0000adf5 adfs + 0x0000adff affs + 0x5346414f afs + 0x09041934 anon-inode filesystem + 0x00000187 autofs + 0x42465331 befs + 0x1badface bfs + 0x42494e4d binfmt_misc + 0x9123683e btrfs + 0x0027e0eb cgroupfs + 0xff534d42 cifs + 0x73757245 coda + 0x012ff7b7 coh + 0x28cd3d45 cramfs + 0x453dcd28 cramfs-wend (wrong endianness) + 0x64626720 debugfs + 0x00001373 devfs + 0x00001cd1 devpts + 0x0000f15f ecryptfs + 0x00414a53 efs + 0x0000137d ext + 0x0000ef53 ext2/ext3 + 0x0000ef51 ext2 + 0x00004006 fat + 0x65735546 fuseblk + 0x65735543 fusectl + 0x0bad1dea futexfs + 0x01161970 gfs2 + 0x47504653 gpfs + 0x00004244 hfs + 0xf995e849 hpfs + 0x958458f6 hugetlbfs + 0x2bad1dea inotifyfs + 0x00009660 isofs + 0x000072b6 jffs2 + 0x3153464a jfs + 0x6b414653 k-afs + 0x0bd00bd0 lustre + 0x0000137f minix + 0x0000138f minix 30 char names + 0x00002468 minix v2 + 0x00002478 minix v2 30 char names + 0x00004d5a minix v3 + 0x19800202 mqueue + 0x00004d44 msdos + 0x0000564c novell + 0x00006969 nfs + 0x6e667364 nfsd + 0x00003434 nilfs + 0x5346544e ntfs + 0x00009fa1 openprom + 0x7461636F ocfs2 + 0x00009fa0 proc + 0x6165676c pstorefs + 0x0000002f qnx4 + 0x858458f6 ramfs + 0x52654973 reiserfs + 0x00007275 romfs + 0x67596969 rpc_pipefs + 0x73636673 securityfs + 0xf97cff8c selinux + 0x0000517b smb + 0x534f434b sockfs + 0x73717368 squashfs + 0x62656572 sysfs + 0x012ff7b6 sysv2 + 0x012ff7b5 sysv4 + 0x01021994 tmpfs + 0x15013346 udf + 0x00011954 ufs + 0x54190100 ufs byteswapped + 0x00009fa2 usbdevfs + 0x01021997 v9fs + 0xa501fcf5 vxfs + 0xabba1974 xenfs + 0x012ff7b4 xenix + 0x58465342 xfs + 0x012fd16d xia + aio_utime $fh_or_path, $atime, $mtime, $callback->($status) Works like perl's "utime" function (including the special case of $atime and $mtime being undef). Fractional times are supported if @@ -537,6 +645,20 @@ aio_truncate $fh_or_path, $offset, $callback->($status) 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. + + $mode can currently be 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. + + The file system block size used by "fallocate" is presumably the + "f_bsize" returned by "statvfs". + + If "fallocate" isn't available or cannot be emulated (currently no + emulation will be attempted), passes -1 and sets $! to "ENOSYS". + aio_chmod $fh_or_path, $mode, $callback->($status) Works like perl's "chmod" function. @@ -865,6 +987,54 @@ aio_mlockall IO::AIO::MCL_FUTURE; + aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents) + Queries the extents of the given file (by calling the Linux "FIEMAP" + ioctl, see for + details). If the ioctl is not available on your OS, then this + request will fail with "ENOSYS". + + $start is the starting offset to query extents for, $length is the + size of the range to query - if it is "undef", then the whole file + will be queried. + + $flags is a combination of flags ("IO::AIO::FIEMAP_FLAG_SYNC" or + "IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is + also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to + query the data portion. + + $count is the maximum number of extent records to return. If it is + "undef", then IO::AIO queries all extents of the range. As a very + special case, if it is 0, then the callback receives the number of + extents instead of the extents themselves (which is unreliable, see + below). + + If an error occurs, the callback receives no arguments. The special + "errno" value "IO::AIO::EBADR" is available to test for flag errors. + + Otherwise, the callback receives an array reference with extent + structures. Each extent structure is an array reference itself, with + the following members: + + [$logical, $physical, $length, $flags] + + Flags is any combination of the following flag values (typically + either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)): + + "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN", + "IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED", + "IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED", + "IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED", + "IO::AIO::FIEMAP_EXTENT_DATA_INLINE", + "IO::AIO::FIEMAP_EXTENT_DATA_TAIL", + "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED" + or "IO::AIO::FIEMAP_EXTENT_SHARED". + + At the time of this writing (Linux 3.2), this requets is unreliable + unless $count is "undef", as the kernel has all sorts of bugs + preventing it to return all extents of a range for files with large + number of extents. The code works around all these issues if $count + is undef. + aio_group $callback->(...) This is a very special aio request: Instead of doing something, it is a container for other aio requests, which is useful if you want @@ -1414,7 +1584,8 @@ IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] Memory-maps a file (or anonymous memory range) and attaches it to - the given $scalar, which will act like a string scalar. + the given $scalar, which will act like a string scalar. Returns true + on success, and false otherwise. The only operations allowed on the scalar are "substr"/"vec" that don't change the string length, and most read-only operations such @@ -1475,6 +1646,24 @@ On systems that do not implement "munlockall", this function returns ENOSYS, otherwise the return value of "munlockall". + IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags + Calls the GNU/Linux splice(2) syscall, if available. If $r_off or + $w_off are "undef", then "NULL" is passed for these, otherwise they + should be the file offset. + + $r_fh and $w_fh should not refer to the same file, as splice might + silently corrupt the data in this case. + + The following symbol flag values are available: + "IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK", + "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT". + + 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 + description for "IO::AIO::splice" above for details. + EVENT LOOP INTEGRATION It is recommended to use AnyEvent::AIO to integrate IO::AIO automatically into many event loops: