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

Comparing IO-AIO/README (file contents):
Revision 1.54 by root, Sun Jan 6 11:48:14 2013 UTC vs.
Revision 1.63 by root, Mon Mar 4 10:28:38 2019 UTC

 NAME
-    IO::AIO - Asynchronous Input/Output
+    IO::AIO - Asynchronous/Advanced Input/Output
 SYNOPSIS
      use IO::AIO;
      aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
     not well-supported or restricted (GNU/Linux doesn't allow them on normal
     files currently, for example), and they would only support aio_read and
     aio_write, so the remaining functionality would have to be implemented
     using threads anyway.
+    In addition to asynchronous I/O, this module also exports some rather
+    arcane interfaces, such as "madvise" or linux's "splice" system call,
+    which is why the "A" in "AIO" can also mean *advanced*.
     Although the module will work in the presence of other (Perl-) threads,
     it is currently not reentrant in any way, so use appropriate locking
     yourself, always call "poll_cb" from within the same thread, or never
     call "poll_cb" (or other "aio_" functions) recursively.
   EXAMPLE
     This is a simple example that uses the EV module and loads /etc/passwd
     asynchronously:
-       use Fcntl;
        use EV;
        use IO::AIO;
        # register the IO::AIO callback with EV
        my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
              # file contents now in $contents
              print $contents;
              # exit event loop and program
-             EV::unloop;
+             EV::break;
           };
        };
        # possibly queue up other requests, or open GUI windows,
        # 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
     not directly visible to Perl.
        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)
-       aio_realpath $pathname, $callback->($link)
+       aio_realpath $pathname, $callback->($path)
        aio_rename $srcpath, $dstpath, $callback->($status)
+       aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
        aio_mkdir $pathname, $mode, $callback->($status)
        aio_rmdir $pathname, $callback->($status)
        aio_readdir $pathname, $callback->($entries)
        aio_readdirx $pathname, $flags, $callback->($entries, $flags)
           IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
        aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
        aio_load $pathname, $data, $callback->($status)
        aio_copy $srcpath, $dstpath, $callback->($status)
        aio_move $srcpath, $dstpath, $callback->($status)
        aio_rmtree $pathname, $callback->($status)
+       aio_fcntl $fh, $cmd, $arg, $callback->($status)
+       aio_ioctl $fh, $request, $buf, $callback->($status)
        aio_sync $callback->($status)
        aio_syncfs $fh, $callback->($status)
        aio_fsync $fh, $callback->($status)
        aio_fdatasync $fh, $callback->($status)
        aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
        aio_pathsync $pathname, $callback->($status)
-       aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
+       aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
        aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
        aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
        aio_mlockall $flags, $callback->($status)
        aio_group $callback->(...)
        aio_nop $callback->()
        IO::AIO::idle_timeout $seconds
        IO::AIO::max_outstanding $maxreqs
        IO::AIO::nreqs
        IO::AIO::nready
        IO::AIO::npending
+       $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]
+       IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]
        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::mremap $scalar, $new_length, $flags[, $new_address]
        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
         "O_APPEND"), the following POSIX and non-POSIX constants are
         available (missing ones on your system are, as usual, 0):
         "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", "O_TTY_INIT"
+        and "O_ACCMODE".
     aio_close $fh, $callback->($status)
         Asynchronously close a file and call the callback with the result
         code.
     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
-        calls the callback without the actual number of bytes read (or -1 on
+        calls the callback with the actual number of bytes transferred (or
-        error, just like the syscall).
+        -1 on error, just like the syscall).
         "aio_read" will, like "sysread", shrink or grow the $data scalar to
         offset plus the actual number of bytes read.
         If $offset is undefined, then the current file descriptor offset
         As native sendfile syscalls (as practically any non-POSIX interface
         hacked together in a hurry to improve benchmark numbers) tend to be
         rather buggy on many systems, this implementation tries to work
         around some known bugs in Linux and FreeBSD kernels (probably
         others, too), but that might fail, so you really really should check
-        the return value of "aio_sendfile" - fewre bytes than expected might
+        the return value of "aio_sendfile" - fewer bytes than expected might
         have been transferred.
     aio_readahead $fh,$offset,$length, $callback->($retval)
         "aio_readahead" populates the page cache with data from a file so
         that subsequent reads from that file will not block on disk I/O. The
         to a page boundary and bytes are read up to the next page boundary
         greater than or equal to (off-set+length). "aio_readahead" does not
         read beyond the end of the file. The current file offset of the file
         is left unchanged.
-        If that syscall doesn't exist (likely if your OS isn't Linux) it
+        If that syscall doesn't exist (likely if your kernel isn't Linux) it
         will be emulated by simply reading the data, which would have a
         similar effect.
     aio_stat $fh_or_path, $callback->($status)
     aio_lstat $fh, $callback->($status)
-        Works like perl's "stat" or "lstat" in void context. The callback
+        Works almost exactly like perl's "stat" or "lstat" in void context.
-        will be called after the stat and the results will be available
+        The callback will be called after the stat and the results will be
-        using "stat _" or "-s _" etc...
+        available using "stat _" or "-s _" and other tests (with the
+        exception of "-B" and "-T").
         The pathname passed to "aio_stat" must be absolute. See API NOTES,
         above, for an explanation.
         Currently, the stats are always 64-bit-stats, i.e. instead of
         back on traditional behaviour).
         "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
         "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
         "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
+        To access higher resolution stat timestamps, see "SUBSECOND STAT
+        TIME ACCESS".
         Example: Print the length of /etc/passwd:
            aio_stat "/etc/passwd", sub {
               $_[0] and die "stat failed: $!";
               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.
-        When called with a pathname, uses utimes(2) if available, otherwise
+        When called with a pathname, uses utimensat(2) or utimes(2) if
-        utime(2). If called on a file descriptor, uses futimes(2) if
+        available, otherwise utime(2). If called on a file descriptor, uses
-        available, otherwise returns ENOSYS, so this is not portable.
+        futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
+        this is not portable.
         Examples:
            # set atime and mtime to current time (basically touch(1)):
            aio_utime "path", undef, 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
+        Allocates or frees disk space according to the $mode argument. See
-        the linux "fallocate" docuemntation for details.
+        the linux "fallocate" documentation for details.
-        $mode can currently be 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to
+        $mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
-        allocate space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
+        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), "FALLOC_FL_ZERO_RANGE", to zero a range,
+        "FALLOC_FL_INSERT_RANGE" to insert a range and
+        "FALLOC_FL_UNSHARE_RANGE" to unshare shared blocks (see your
+        fallocate(2) manpage).
         The file system block size used by "fallocate" is presumably the
-        "f_bsize" returned by "statvfs".
+        "f_bsize" returned by "statvfs", but different filesystems and
+        filetypes can dictate other limitations.
         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)
         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_rename2 $srcpath, $dstpath, $flags, $callback->($status)
+        Basically a version of "aio_rename" with an additional $flags
+        argument. Calling this with "$flags=0" is the same as calling
+        "aio_rename".
+        Non-zero flags are currently only supported on GNU/Linux systems
+        that support renameat2. Other systems fail with "ENOSYS" in this
+        case.
+        The following constants are available (missing ones are, as usual
+        0), see renameat2(2) for details:
+        "IO::AIO::RENAME_NOREPLACE", "IO::AIO::RENAME_EXCHANGE" and
+        "IO::AIO::RENAME_WHITEOUT".
     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
         request is executed, so do not change your umask.
         The flags are a combination of the following constants, ORed
         together (the flags will also be passed to the callback, possibly
         modified):
         IO::AIO::READDIR_DENTS
-            When this flag is off, then the callback gets an arrayref
+            Normally the callback gets an arrayref consisting of names only
-            consisting of names only (as with "aio_readdir"), otherwise it
+            (as with "aio_readdir"). If this flag is set, then the callback
             gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
-            describing a single directory entry in more detail.
+            describing a single directory entry in more detail:
             $name is the name of the entry.
             $type is one of the "IO::AIO::DT_xxx" constants:
             "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
             "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
             "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
             "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
-            you need to know, you have to run stat yourself. Also, for speed
+            you need to know, you have to run stat yourself. Also, for
-            reasons, the $type scalars are read-only: you can not modify
+            speed/memory reasons, the $type scalars are read-only: you must
-            them.
+            not modify them.
             $inode is the inode number (which might not be exact on systems
             with 64 bit inode numbers and 32 bit perls). This field has
             unspecified content on systems that do not deliver the inode
             information.
             of which names with short names are tried first.
         IO::AIO::READDIR_STAT_ORDER
             When this flag is set, then the names will be returned in an
             order suitable for stat()'ing each one. That is, when you plan
-            to stat() all files in the given directory, then the returned
+            to stat() most or all files in the given directory, then the
-            order will likely be fastest.
+            returned order will likely be faster.
             If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
             specified, then the likely dirs come first, resulting in a less
-            optimal stat order.
+            optimal stat order for stat'ing all entries, but likely a more
+            optimal order for finding subdirectories.
         IO::AIO::READDIR_FOUND_UNKNOWN
             This flag should not be set when calling "aio_readdirx".
             Instead, it is being set by "aio_readdirx", when any of the
             $type's found were "IO::AIO::DT_UNKNOWN". The absence of this
             flag therefore indicates that all $type's are known, which can
             be used to speed up some algorithms.
+    aio_slurp $pathname, $offset, $length, $data, $callback->($status)
+        Opens, reads and closes the given file. The data is put into $data,
+        which is resized as required.
+        If $offset is negative, then it is counted from the end of the file.
+        If $length is zero, then the remaining length of the file is used.
+        Also, in this case, the same limitations to modifying $data apply as
+        when IO::AIO::mmap is used, i.e. it must only be modified in-place
+        with "substr". If the size of the file is known, specifying a
+        non-zero $length results in a performance advantage.
+        This request is similar to the older "aio_load" request, but since
+        it is a single request, it might be more efficient to use.
+        Example: load /etc/passwd into $passwd.
+           my $passwd;
+           aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
+              $_[0] >= 0
+                 or die "/etc/passwd: $!\n";
+              printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
+              print $passwd;
+           };
+           IO::AIO::flush;
     aio_load $pathname, $data, $callback->($status)
         This is a composite request that tries to fully load the given file
         into memory. Status is the same as with aio_read.
+        Using "aio_slurp" might be more efficient, as it is a single
+        request.
     aio_copy $srcpath, $dstpath, $callback->($status)
         Try to copy the *file* (directories not supported as either source
         or destination) from $srcpath to $dstpath and call the callback with
         a status of 0 (ok) or -1 (error, see $!).
+        Existing destination files will be truncated.
         This is a composite request that creates the destination file with
         mode 0200 and copies the contents of the source file into it using
         "aio_sendfile", followed by restoring atime, mtime, access mode and
         uid/gid, in that order.
         to efficiently separate the entries of directory $path into two sets
         of names, directories you can recurse into (directories), and ones
         you cannot recurse into (everything else, including symlinks to
         directories).
-        "aio_scandir" is a composite request that creates of many sub
+        "aio_scandir" is a composite request that generates many sub
-        requests_ $maxreq specifies the maximum number of outstanding aio
+        requests. $maxreq specifies the maximum number of outstanding aio
         requests that this function generates. If it is "<= 0", then a
         suitable default will be chosen (currently 4).
         On error, the callback is called without arguments, otherwise it
         receives two array-refs with path-relative entry names.
         Delete a directory tree starting (and including) $path, return the
         status of the final "rmdir" only. This is a composite request that
         uses "aio_scandir" to recurse into and rmdir directories, and unlink
         everything else.
+    aio_fcntl $fh, $cmd, $arg, $callback->($status)
+    aio_ioctl $fh, $request, $buf, $callback->($status)
+        These work just like the "fcntl" and "ioctl" built-in functions,
+        except they execute asynchronously and pass the return value to the
+        callback.
+        Both calls can be used for a lot of things, some of which make more
+        sense to run asynchronously in their own thread, while some others
+        make less sense. For example, calls that block waiting for external
+        events, such as locking, will also lock down an I/O thread while it
+        is waiting, which can deadlock the whole I/O system. At the same
+        time, there might be no alternative to using a thread to wait.
+        So in general, you should only use these calls for things that do
+        (filesystem) I/O, not for things that wait for other events
+        (network, other processes), although if you are careful and know
+        what you are doing, you still can.
+        The following constants are available (missing ones are, as usual
+        0):
+        "F_DUPFD_CLOEXEC",
+        "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
+        "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
+        "FIDEDUPERANGE".
+        "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
+        "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
+        "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
+        "FS_IOC_SET_ENCRYPTION_POLICY", "FS_IOC_GET_ENCRYPTION_PWSALT",
+        "FS_IOC_GET_ENCRYPTION_POLICY", "FS_KEY_DESCRIPTOR_SIZE".
+        "FS_SECRM_FL", "FS_UNRM_FL", "FS_COMPR_FL", "FS_SYNC_FL",
+        "FS_IMMUTABLE_FL", "FS_APPEND_FL", "FS_NODUMP_FL", "FS_NOATIME_FL",
+        "FS_DIRTY_FL", "FS_COMPRBLK_FL", "FS_NOCOMP_FL", "FS_ENCRYPT_FL",
+        "FS_BTREE_FL", "FS_INDEX_FL", "FS_JOURNAL_DATA_FL", "FS_NOTAIL_FL",
+        "FS_DIRSYNC_FL", "FS_TOPDIR_FL", "FS_FL_USER_MODIFIABLE".
+        "FS_XFLAG_REALTIME", "FS_XFLAG_PREALLOC", "FS_XFLAG_IMMUTABLE",
+        "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
+        "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
+        "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
+        "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
+        "FS_XFLAG_HASATTR",
     aio_sync $callback->($status)
         Asynchronously call sync and call the callback when finished.
     aio_fsync $fh, $callback->($status)
         Asynchronously call fsync on the given filehandle and call the
         Future versions of this function might fall back to other methods
         when "fsync" on the directory fails (such as calling "sync").
         Passes 0 when everything went ok, and -1 on error.
-    aio_msync $scalar, $offset = 0, $length = undef, flags = 0,
+    aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC,
     $callback->($status)
         This is a rather advanced IO::AIO call, which only works on
         mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
         also works on data scalars managed by the Sys::Mmap or Mmap modules,
         note that the scalar must only be modified in-place while an aio
         It calls the "msync" function of your OS, if available, with the
         memory area starting at $offset in the string and ending $length
         bytes later. If $length is negative, counts from the end, and if
         $length is "undef", then it goes till the end of the string. The
-        flags can be a combination of "IO::AIO::MS_ASYNC",
+        flags can be either "IO::AIO::MS_ASYNC" or "IO::AIO::MS_SYNC", plus
-        "IO::AIO::MS_INVALIDATE" and "IO::AIO::MS_SYNC".
+        an optional "IO::AIO::MS_INVALIDATE".
     aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
     $callback->($status)
         This is a rather advanced IO::AIO call, which works best on
         mmap(2)ed scalars.
            IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
            aio_mlock $data; # mlock in background
     aio_mlockall $flags, $callback->($status)
         Calls the "mlockall" function with the given $flags (a combination
-        of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
+        of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
+        "IO::AIO::MCL_ONFAULT").
         On systems that do not implement "mlockall", this function returns
-        -1 and sets errno to "ENOSYS".
+        -1 and sets errno to "ENOSYS". Similarly, flag combinations not
+        supported by the system result in a return value of -1 with errno
+        being set to "EINVAL".
         Note that the corresponding "munlockall" is synchronous and is
         documented under "MISCELLANEOUS FUNCTIONS".
         Example: asynchronously lock all current and future pages into
         "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
+        At the time of this writing (Linux 3.2), this request 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
+        preventing it to return all extents of a range for files with a
-        number of extents. The code works around all these issues if $count
+        large number of extents. The code (only) works around all these
-        is undef.
+        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
           aio_stat [$etcdir, "passwd"], sub {
              # yay
           };
        };
-    That "aio_wd" is a request and not a normal function shows that creating
+    The fact that "aio_wd" is a request and not a normal function shows that
-    an IO::AIO::WD object is itself a potentially blocking operation, which
+    creating an IO::AIO::WD object is itself a potentially blocking
-    is why it is done asynchronously.
+    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:
        aio_lstat "/etc"    , sub { ...  # pathname as normal string
     There are some caveats: when directories get renamed (or deleted), the
     pathname string doesn't change, so will point to the new directory (or
     nowhere at all), while the directory fd, if available on the system,
     will still point to the original directory. Most functions accepting a
     pathname will use the directory fd on newer systems, and the string on
-    older systems. Some functions (such as realpath) will always rely on the
+    older systems. Some functions (such as "aio_realpath") will always rely
-    string form of the pathname.
+    on the string form of the pathname.
     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).
         instead of a working directory object and $! is set appropriately.
         Since passing "undef" as working directory component of a pathname
         fails the request with "ENOENT", there is often no need for error
         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.
         Strictly equivalent to:
            IO::AIO::poll_wait, IO::AIO::poll_cb
               while IO::AIO::nreqs;
+        This function can be useful at program aborts, to make sure
+        outstanding I/O has been done ("IO::AIO" uses an "END" block which
+        already calls this function on normal exits), or when you are merely
+        using "IO::AIO" for its more advanced functions, rather than for
+        async I/O, e.g.:
+           my ($dirs, $nondirs);
+           IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
+           IO::AIO::flush;
+           # $dirs, $nondirs are now set
     IO::AIO::max_poll_reqs $nreqs
     IO::AIO::max_poll_time $seconds
         These set the maximum number of requests (default 0, meaning
         infinity) that are being processed by "IO::AIO::poll_cb" in one
         call, respectively the maximum amount of time (default 0, meaning
         This is a very bad function to use in interactive programs because
         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:
+        stat a lot of files, you can write something like this:
            IO::AIO::max_outstanding 32;
            for my $path (...) {
               aio_stat $path , ...;
     IO::AIO::npending
         Returns the number of requests currently in the pending state
         (executed, but not yet processed by poll_cb).
+   SUBSECOND STAT TIME ACCESS
+    Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
+    generally find access/modification and change times with subsecond time
+    accuracy of the system supports it, but perl's built-in functions only
+    return the integer part.
+    The following functions return the timestamps of the most recent stat
+    with subsecond precision on most systems and work both after
+    "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
+    value is only meaningful after a successful "stat"/"lstat" call, or
+    during/after a successful "aio_stat"/"aio_lstat" callback.
+    This is similar to the Time::HiRes "stat" functions, but can return full
+    resolution without rounding and work with standard perl "stat",
+    alleviating the need to call the special "Time::HiRes" functions, which
+    do not act like their perl counterparts.
+    On operating systems or file systems where subsecond time resolution is
+    not supported or could not be detected, a fractional part of 0 is
+    returned, so it is always safe to call these functions.
+    $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
+    IO::AIO::st_btime
+        Return the access, modication, change or birth time, respectively,
+        including fractional part. Due to the limited precision of floating
+        point, the accuracy on most platforms is only a bit better than
+        milliseconds for times around now - see the *nsec* function family,
+        below, for full accuracy.
+        File birth time is only available when the OS and perl support it
+        (on FreeBSD and NetBSD at the time of this writing, although support
+        is adaptive, so if your OS/perl gains support, IO::AIO can take
+        avdantage of it). On systems where it isn't available, 0 is
+        currently returned, but this might change to "undef" in a future
+        version.
+    ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
+        Returns access, modification, change and birth time all in one go,
+        and maybe more times in the future version.
+    $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
+    IO::AIO::st_ctimensec, IO::AIO::st_btimensec
+        Return the fractional access, modifcation, change or birth time, in
+        nanoseconds, as an integer in the range 0 to 999999999.
+        Note that no accessors are provided for access, modification and
+        change times - you need to get those from "stat _" if required ("int
+        IO::AIO::st_atime" and so on will *not* generally give you the
+        correct value).
+    $seconds = IO::AIO::st_btimesec
+        The (integral) seconds part of the file birth time, if available.
+    ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
+        Like the functions above, but returns all four times in one go (and
+        maybe more in future versions).
+    $counter = IO::AIO::st_gen
+        Returns the generation counter (in practice this is just a random
+        number) of the file. This is only available on platforms which have
+        this member in their "struct stat" (most BSDs at the time of this
+        writing) and generally only to the root usert. If unsupported, 0 is
+        returned, but this might change to "undef" in a future version.
+    Example: print the high resolution modification time of /etc, using
+    "stat", and "IO::AIO::aio_stat".
+       if (stat "/etc") {
+          printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
+       }
+       IO::AIO::aio_stat "/etc", sub {
+          $_[0]
+             and return;
+          printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
+       };
+       IO::AIO::flush;
+    Output of the awbove on my system, showing reduced and full accuracy:
+       stat(/etc) mtime: 1534043702.020808
+       aio_stat(/etc) mtime: 1534043702.020807792
    MISCELLANEOUS FUNCTIONS
-    IO::AIO implements some functions that might be useful, but are not
+    IO::AIO implements some functions that are useful when you want to use
-    asynchronous.
+    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.
+    $numfd = IO::AIO::get_fdlimit
+        This function is *EXPERIMENTAL* and subject to change.
+        Tries to find the current file descriptor limit and returns it, or
+        "undef" and sets $! in case of an error. The limit is one larger
+        than the highest valid file descriptor number.
+    IO::AIO::min_fdlimit [$numfd]
+        This function is *EXPERIMENTAL* and subject to change.
+        Try to increase the current file descriptor limit(s) to at least
+        $numfd by changing the soft or hard file descriptor resource limit.
+        If $numfd is missing, it will try to set a very high limit, although
+        this is not recommended when you know the actual minimum that you
+        require.
+        If the limit cannot be raised enough, the function makes a
+        best-effort attempt to increase the limit as much as possible, using
+        various tricks, while still failing. You can query the resulting
+        limit using "IO::AIO::get_fdlimit".
+        If an error occurs, returns "undef" and sets $!, otherwise returns
+        true.
     IO::AIO::sendfile $ofh, $ifh, $offset, $count
         Calls the "eio_sendfile_sync" function, which is like
         "aio_sendfile", but is blocking (this makes most sense if you know
         the input data is likely cached already and the output filehandle is
         details). The following advice constants are available:
         "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
         "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
         "IO::AIO::MADV_DONTNEED".
+        If $offset is negative, counts from the end. If $length is negative,
+        the remaining length of the $scalar is used. If possible, $length
+        will be reduced to fit into the $scalar.
         On systems that do not implement "posix_madvise", this function
         returns ENOSYS, otherwise the return value of "posix_madvise".
     IO::AIO::mprotect $scalar, $offset, $len, $protect
         Simply calls the "mprotect" function on the preferably AIO::mmap'ed
         $scalar (see its manpage for details). The following protect
         constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
         "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
+        If $offset is negative, counts from the end. If $length is negative,
+        the remaining length of the $scalar is used. If possible, $length
+        will be reduced to fit into the $scalar.
         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. Returns true
         on success, and false otherwise.
+        The scalar must exist, but its contents do not matter - this means
+        you cannot use a nonexistant array or hash element. When in doubt,
+        "undef" the scalar first.
-        The only operations allowed on the scalar are "substr"/"vec" that
+        The only operations allowed on the mmapped scalar are
-        don't change the string length, and most read-only operations such
+        "substr"/"vec", which don't change the string length, and most
-        as copying it or searching it with regexes and so on.
+        read-only operations such as copying it or searching it with regexes
+        and so on.
         Anything else is unsafe and will, at best, result in memory leaks.
         The memory map associated with the $scalar is automatically removed
-        when the $scalar is destroyed, or when the "IO::AIO::mmap" or
+        when the $scalar is undef'd or destroyed, or when the
-        "IO::AIO::munmap" functions are called.
+        "IO::AIO::mmap" or "IO::AIO::munmap" functions are called on it.
         This calls the "mmap"(2) function internally. See your system's
         manual page for details on the $length, $prot and $flags parameters.
         The $length must be larger than zero and smaller than the actual
         "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
         "IO::AIO::PROT_WRITE",
         $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"
+        not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
-        (which is set to "MAP_ANON" if your system only provides this
+        "MAP_ANON" if your system only provides this constant),
+        "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
-        constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
+        "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
+        "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
-        "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or
+        "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or
-        "IO::AIO::MAP_NONBLOCK"
+        "IO::AIO::MAP_STACK".
         If $fh is "undef", then a file descriptor of -1 is passed.
         $offset is the offset from the start of the file - it generally must
         be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
            my $fast_md5 = md5 $data;
     IO::AIO::munmap $scalar
         Removes a previous mmap and undefines the $scalar.
+    IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
+    $new_address = 0]
+        Calls the Linux-specific mremap(2) system call. The $scalar must
+        have been mapped by "IO::AIO::mmap", and $flags must currently
+        either be 0 or "IO::AIO::MREMAP_MAYMOVE".
+        Returns true if successful, and false otherwise. If the underlying
+        mmapped region has changed address, then the true value has the
+        numerical value 1, otherwise it has the numerical value 0:
+           my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
+              or die "mremap: $!";
+           if ($success*1) {
+              warn "scalar has chanegd address in memory\n";
+           }
+        "IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
+        implemented, but not supported and might go away in a future
+        version.
+        On systems where this call is not supported or is not emulated, this
+        call returns falls and sets $! to "ENOSYS".
+    IO::AIO::mlockall $flags
+        Calls the "eio_mlockall_sync" function, which is like
+        "aio_mlockall", but is blocking.
     IO::AIO::munlock $scalar, $offset = 0, $length = undef
         Calls the "munlock" function, undoing the effects of a previous
         "aio_mlock" call (see its description for details).
         "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
+        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.
+        Example: create a pipe race-free w.r.t. threads and fork:
+           my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
+              or die "pipe2: $!\n";
+    $fh = IO::AIO::eventfd [$initval, [$flags]]
+        This is a direct interface to the Linux eventfd(2) system call. The
+        (unhelpful) defaults for $initval and $flags are 0 for both.
+        On success, the new eventfd filehandle is returned, otherwise
+        returns "undef". If the eventfd syscall is missing, fails with
+        "ENOSYS".
+        Please refer to eventfd(2) for more info on this call.
+        The following symbol flag values are available:
+        "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
+        "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
+        Example: create a new eventfd filehandle:
+           $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC
+              or die "eventfd: $!\n";
+    $fh = IO::AIO::timerfd_create $clockid[, $flags]
+        This is a direct interface to the Linux timerfd_create(2) system
+        call. The (unhelpful) default for $flags is 0.
+        On success, the new timerfd filehandle is returned, otherwise
+        returns "undef". If the eventfd syscall is missing, fails with
+        "ENOSYS".
+        Please refer to timerfd_create(2) for more info on this call.
+        The following $clockid values are available:
+        "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
+        "IO::AIO::CLOCK_CLOCK_BOOTTIME" (Linux 3.15)
+        "IO::AIO::CLOCK_CLOCK_REALTIME_ALARM" (Linux 3.11) and
+        "IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM" (Linux 3.11).
+        The following $flags values are available (Linux 2.6.27):
+        "IO::AIO::TFD_NONBLOCK" and "IO::AIO::TFD_CLOEXEC".
+        Example: create a new timerfd and set it to one-second repeated
+        alarms, then wait for two alarms:
+           my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
+              or die "timerfd_create: $!\n";
+           defined IO::AIO::timerfd_settime $fh, 0, 1, 1
+              or die "timerfd_settime: $!\n";
+           for (1..2) {
+              8 == sysread $fh, my $buf, 8
+                 or die "timerfd read failure\n";
+              printf "number of expirations (likely 1): %d\n",
+                 unpack "Q", $buf;
+           }
+    ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags,
+    $new_interval, $nbw_value
+        This is a direct interface to the Linux timerfd_settime(2) system
+        call. Please refer to its manpage for more info on this call.
+        The new itimerspec is specified using two (possibly fractional)
+        second values, $new_interval and $new_value).
+        On success, the current interval and value are returned (as per
+        "timerfd_gettime"). On failure, the empty list is returned.
+        The following $flags values are available:
+        "IO::AIO::TFD_TIMER_ABSTIME" and "IO::AIO::TFD_TIMER_CANCEL_ON_SET".
+        See "IO::AIO::timerfd_create" for a full example.
+    ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
+        This is a direct interface to the Linux timerfd_gettime(2) system
+        call. Please refer to its manpage for more info on this call.
+        On success, returns the current values of interval and value for the
+        given timerfd (as potentially fractional second values). On failure,
+        the empty list is returned.
 EVENT LOOP INTEGRATION
     It is recommended to use AnyEvent::AIO to integrate IO::AIO
     automatically into many event loops:
         forking, if "IO::AIO" was used in the parent. Calling it while
         IO::AIO is active in the process will result in undefined behaviour.
         Calling it at any time will also result in any undefined (by POSIX)
         behaviour.
+  LINUX-SPECIFIC CALLS
+    When a call is documented as "linux-specific" then this means it
+    originated on GNU/Linux. "IO::AIO" will usually try to autodetect the
+    availability and compatibility of such calls regardless of the platform
+    it is compiled on, so platforms such as FreeBSD which often implement
+    these calls will work. When in doubt, call them and see if they fail wth
+    "ENOSYS".
   MEMORY USAGE
     Per-request usage:
     Each aio request uses - depending on your architecture - around 100-200
     bytes of memory. In addition, stat requests need a stat buffer (possibly
     In the execution phase, some aio requests require more memory for
     temporary buffers, and each thread requires a stack and other data
     structures (usually around 16k-128k, depending on the OS).
 KNOWN BUGS
-    Known bugs will be fixed in the next release.
+    Known bugs will be fixed in the next release :)
+KNOWN ISSUES
+    Calls that try to "import" foreign memory areas (such as "IO::AIO::mmap"
+    or "IO::AIO::aio_slurp") do not work with generic lvalues, such as
+    non-created hash slots or other scalars I didn't think of. It's best to
+    avoid such and either use scalar variables or making sure that the
+    scalar exists (e.g. by storing "undef") and isn't "funny" (e.g. tied).
+    I am not sure anything can be done about this, so this is considered a
+    known issue, rather than a bug.
 SEE ALSO
     AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
     more natural syntax.

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.54 by root, Sun Jan 6 11:48:14 2013 UTC vs. Revision 1.63 by root, Mon Mar 4 10:28:38 2019 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.54 by root, Sun Jan 6 11:48:14 2013 UTC vs.
Revision 1.63 by root, Mon Mar 4 10:28:38 2019 UTC