[ViewVC] Diff of: cvs/IO-AIO/README

Comparing IO-AIO/README (file contents):
Revision 1.51 by root, Sat Apr 7 00:50:33 2012 UTC vs.
Revision 1.53 by root, Thu Oct 11 03:20:52 2012 UTC

         the actual aio request is severed and calling its methods will
         either do nothing or result in a runtime error).
 FUNCTIONS
   QUICK OVERVIEW
-    This section simply lists the prototypes of the most important functions
+    This section simply lists the prototypes most of the functions for quick
-    for quick reference. See the following sections for function-by-function
+    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_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_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)
        aio_symlink $srcpath, $dstpath, $callback->($status)
        aio_readlink $pathname, $callback->($link)
        IO::AIO::nready
        IO::AIO::npending
        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
         Similar to "aioreq_pri", but subtracts the given value from the
         current priority, so the effect is cumulative.
     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.
         The $flags argument is a bitmask. See the "Fcntl" module for a list.
         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
         $offset into the scalar given by $data and offset $dataoffset and
               namemax => 255,
               frsize  => 1024,
               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
         the underlying syscalls support them.
            # same as above:
            aio_chown "path", 0, undef;
     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.
     aio_unlink $pathname, $callback->($status)
         memory.
            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
+        Queries the extents of the given file (by calling the Linux "FIEMAP"
         ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for
-        details). If the "ioctl" is not available on your OS, then this
+        details). If the ioctl is not available on your OS, then this
-        rquiest will fail with "ENOSYS".
+        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.
         "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 file. As a very
+        "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.
+        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
         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"):
+        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
         to bundle many requests into a single, composite, request with a
         definite callback and the ability to cancel the whole request with
         On systems that do not implement "mprotect", this function returns
         ENOSYS, otherwise the return value of "mprotect".
     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
         as copying it or searching it with regexes and so on.
     IO::AIO::munlockall
         Calls the "munlockall" function.
         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:

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.51 by root, Sat Apr 7 00:50:33 2012 UTC vs. Revision 1.53 by root, Thu Oct 11 03:20:52 2012 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.51 by root, Sat Apr 7 00:50:33 2012 UTC vs.
Revision 1.53 by root, Thu Oct 11 03:20:52 2012 UTC