[ViewVC] Diff of: cvs/IO-AIO/AIO.pm

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.240 by root, Mon Dec 17 06:18:39 2012 UTC vs.
Revision 1.315 by root, Mon Sep 5 00:03:32 2022 UTC

 =head1 NAME
-IO::AIO - Asynchronous Input/Output
+IO::AIO - Asynchronous/Advanced Input/Output
 =head1 SYNOPSIS
  use IO::AIO;
 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 C<madvise> or linux's C<splice> system call,
+which is why the C<A> in C<AIO> can also mean I<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 C<poll_cb> from within the same thread, or never
 call C<poll_cb> (or other C<aio_> functions) recursively.
 =head2 EXAMPLE
 This is a simple example that uses the EV module and loads
 F</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;
 =head1 REQUEST ANATOMY AND LIFETIME
 Every C<aio_*> function creates a request. which is a C data structure not
 directly visible to Perl.
 use common::sense;
 use base 'Exporter';
 BEGIN {
-   our $VERSION = '4.18';
+   our $VERSION = 4.77;
    our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
-                     aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
+                     aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl
-                     aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_allocate
+                     aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
-                     aio_pathsync aio_readahead aio_fiemap
+                     aio_pathsync aio_readahead aio_fiemap aio_allocate
-                     aio_rename aio_link aio_move aio_copy aio_group
+                     aio_rename aio_rename2 aio_link aio_move aio_copy aio_group
                      aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
                      aio_chmod aio_utime aio_truncate
                      aio_msync aio_mtouch aio_mlock aio_mlockall
                      aio_statvfs
+                     aio_slurp
                      aio_wd);
    our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
    our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
                        min_parallel max_parallel max_idle idle_timeout
                        nreqs nready npending nthreads
                        max_poll_time max_poll_reqs
                        sendfile fadvise madvise
-                       mmap munmap munlock munlockall);
+                       mmap munmap mremap munlock munlockall
+                       accept4 tee splice pipe2 pipesize
+                       fexecve memfd_create eventfd
+                       timerfd_create timerfd_settime timerfd_gettime
+                       pidfd_open pidfd_send_signal pidfd_getfd);
    push @AIO_REQ, qw(aio_busy); # not exported
    @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
    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
+   IO::AIO::reinit
+   $nfd = IO::AIO::get_fdlimit
+   IO::AIO::min_fdlimit $nfd
    IO::AIO::sendfile $ofh, $ifh, $offset, $count
    IO::AIO::fadvise $fh, $offset, $len, $advice
+   IO::AIO::fexecve $fh, $argv, $envp
    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
+   # stat extensions
+   $counter = IO::AIO::st_gen
+   $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
+   ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
+   $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
+   $seconds = IO::AIO::st_btimesec
+   ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
+   # very much unportable syscalls
+   IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
+   IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
+   IO::AIO::tee $r_fh, $w_fh, $length, $flags
+   $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
+   ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
+   $fh = IO::AIO::eventfd [$initval, [$flags]]
+   $fh = IO::AIO::memfd_create $pathname[, $flags]
+   $fh = IO::AIO::timerfd_create $clockid[, $flags]
+   ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
+   ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
+   $fh = IO::AIO::pidfd_open $pid[, $flags]
+   $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
+   $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
 =head2 API NOTES
 All the C<aio_*> calls are more or less thin wrappers around the syscall
 with the same name (sans C<aio_>). The arguments are similar or identical,
 following POSIX and non-POSIX constants are available (missing ones on
 your system are, as usual, C<0>):
 C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
 C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
-C<O_RSYNC>, C<O_SYNC> and C<O_TTY_INIT>.
+C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, C<O_TTY_INIT> and C<O_ACCMODE>.
 =item aio_close $fh, $callback->($status)
 Asynchronously close a file and call the callback with the result
 =item aio_read  $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
 =item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
 Reads or writes C<$length> bytes from or to the specified C<$fh> and
-C<$offset> into the scalar given by C<$data> and offset C<$dataoffset>
+C<$offset> into the scalar given by C<$data> and offset C<$dataoffset> and
-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 -1 on
 error, just like the syscall).
 C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to
 offset plus the actual number of bytes read.
 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 C<aio_sendfile> -
-fewre bytes than expected might have been transferred.
+fewer bytes than expected might have been transferred.
 =item aio_readahead $fh,$offset,$length, $callback->($retval)
 C<aio_readahead> populates the page cache with data from a file so that
 whole pages, so that offset is effectively rounded down to a page boundary
 and bytes are read up to the next page boundary greater than or equal to
 (off-set+length). C<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 will be
+If that syscall doesn't exist (likely if your kernel isn't Linux) it will
-emulated by simply reading the data, which would have a similar effect.
+be emulated by simply reading the data, which would have a similar effect.
 =item aio_stat  $fh_or_path, $callback->($status)
 =item aio_lstat $fh, $callback->($status)
-Works like perl's C<stat> or C<lstat> in void context. The callback will
+Works almost exactly like perl's C<stat> or C<lstat> in void context. The
-be called after the stat and the results will be available using C<stat _>
+callback will be called after the stat and the results will be available
-or C<-s _> etc...
+using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
+and C<-T>).
 The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
 for an explanation.
 Currently, the stats are always 64-bit-stats, i.e. instead of returning an
 behaviour).
 C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
 C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
 C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
+To access higher resolution stat timestamps, see L<SUBSECOND STAT TIME
+ACCESS>.
 Example: Print the length of F</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 C<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
 =item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
 Works like perl's C<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 available,
-utime(2). If called on a file descriptor, uses futimes(2) if available,
+otherwise utime(2). If called on a file descriptor, uses futimens(2)
-otherwise returns ENOSYS, so this is not portable.
+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;
 Works like truncate(2) or ftruncate(2).
 =item aio_allocate $fh, $mode, $offset, $len, $callback->($status)
-Allocates or freed disk space according to the C<$mode> argument. See the
+Allocates or frees disk space according to the C<$mode> argument. See the
-linux C<fallocate> docuemntation for details.
+linux C<fallocate> documentation for details.
-C<$mode> can currently be C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE>
+C<$mode> is usually C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> to allocate
-to allocate space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE |
+space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE>,
-IO::AIO::FALLOC_FL_KEEP_SIZE>, to deallocate a file range.
+to deallocate a file range.
+IO::AIO also supports C<FALLOC_FL_COLLAPSE_RANGE>, to remove a range
+(without leaving a hole), C<FALLOC_FL_ZERO_RANGE>, to zero a range,
+C<FALLOC_FL_INSERT_RANGE> to insert a range and C<FALLOC_FL_UNSHARE_RANGE>
+to unshare shared blocks (see your L<fallocate(2)> manpage).
 The file system block size used by C<fallocate> is presumably the
-C<f_bsize> returned by C<statvfs>.
+C<f_bsize> returned by C<statvfs>, but different filesystems and filetypes
+can dictate other limitations.
 If C<fallocate> isn't available or cannot be emulated (currently no
 emulation will be attempted), passes C<-1> and sets C<$!> to C<ENOSYS>.
 =item aio_rename $srcpath, $dstpath, $callback->($status)
 Asynchronously rename the object at C<$srcpath> to C<$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 C<[$wd, "."]> as C<$srcpath> is specialcased - instead
+of failing, C<rename> is called on the absolute path of C<$wd>.
+=item aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
+Basically a version of C<aio_rename> with an additional C<$flags>
+argument. Calling this with C<$flags=0> is the same as calling
+C<aio_rename>.
+Non-zero flags are currently only supported on GNU/Linux systems that
+support renameat2. Other systems fail with C<ENOSYS> in this case.
+The following constants are available (missing ones are, as usual C<0>),
+see renameat2(2) for details:
+C<IO::AIO::RENAME_NOREPLACE>, C<IO::AIO::RENAME_EXCHANGE>
+and C<IO::AIO::RENAME_WHITEOUT>.
 =item aio_mkdir $pathname, $mode, $callback->($status)
 Asynchronously mkdir (create) a directory and call the callback with
 the result code. C<$mode> will be modified by the umask at the time the
 =item aio_rmdir $pathname, $callback->($status)
 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 C<[$wd, "."]> is specialcased - instead of failing,
+C<rmdir> is called on the absolute path of C<$wd>.
 =item aio_readdir $pathname, $callback->($entries)
 Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
 directory (i.e. opendir + readdir + closedir). The entries will not be
 =over 4
 =item IO::AIO::READDIR_DENTS
-When this flag is off, then the callback gets an arrayref consisting of
+Normally the callback gets an arrayref consisting of names only (as
-names only (as with C<aio_readdir>), otherwise it gets an arrayref with
+with C<aio_readdir>). If this flag is set, then the callback gets an
-C<[$name, $type, $inode]> arrayrefs, each describing a single directory
+arrayref with C<[$name, $type, $inode]> arrayrefs, each describing a
-entry in more detail.
+single directory entry in more detail:
 C<$name> is the name of the entry.
 C<$type> is one of the C<IO::AIO::DT_xxx> constants:
 C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>,
 C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>,
 C<IO::AIO::DT_WHT>.
-C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to
+C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need
-know, you have to run stat yourself. Also, for speed reasons, the C<$type>
+to know, you have to run stat yourself. Also, for speed/memory reasons,
-scalars are read-only: you can not modify them.
+the C<$type> scalars are read-only: you must not modify them.
 C<$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.
 short names are tried first.
 =item 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()
+suitable for stat()'ing each one. That is, when you plan to stat() most or
-all files in the given directory, then the returned order will likely
+all files in the given directory, then the returned order will likely be
-be fastest.
+faster.
-If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, then
+If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified,
-the likely dirs come first, resulting in a less optimal stat order.
+then the likely dirs come first, resulting in a less optimal stat order
+for stat'ing all entries, but likely a more optimal order for finding
+subdirectories.
 =item IO::AIO::READDIR_FOUND_UNKNOWN
 This flag should not be set when calling C<aio_readdirx>. Instead, it
 is being set by C<aio_readdirx>, when any of the C<$type>'s found were
 C<$type>'s are known, which can be used to speed up some algorithms.
 =back
+=item aio_slurp $pathname, $offset, $length, $data, $callback->($status)
+Opens, reads and closes the given file. The data is put into C<$data>,
+which is resized as required.
+If C<$offset> is negative, then it is counted from the end of the file.
+If C<$length> is zero, then the remaining length of the file is
+used. Also, in this case, the same limitations to modifying C<$data> apply
+as when IO::AIO::mmap is used, i.e. it must only be modified in-place
+with C<substr>. If the size of the file is known, specifying a non-zero
+C<$length> results in a performance advantage.
+This request is similar to the older C<aio_load> request, but since it is
+a single request, it might be more efficient to use.
+Example: load F</etc/passwd> into C<$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;
 =item 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 C<aio_slurp> might be more efficient, as it is a single request.
 =cut
 sub aio_load($$;$) {
    my ($path, undef, $cb) = @_;
 =item aio_copy $srcpath, $dstpath, $callback->($status)
 Try to copy the I<file> (directories not supported as either source or
 destination) from C<$srcpath> to C<$dstpath> and call the callback with
 a status of C<0> (ok) or C<-1> (error, see C<$!>).
+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
 C<aio_sendfile>, followed by restoring atime, mtime, access mode and
 uid/gid, in that order.
 Scans a directory (similar to C<aio_readdir>) but additionally tries to
 efficiently separate the entries of directory C<$path> into two sets of
 names, directories you can recurse into (directories), and ones you cannot
 recurse into (everything else, including symlinks to directories).
-C<aio_scandir> is a composite request that creates of many sub requests_
+C<aio_scandir> is a composite request that generates many sub requests.
 C<$maxreq> specifies the maximum number of outstanding aio requests that
 this function generates. If it is C<< <= 0 >>, then a suitable default
 will be chosen (currently 4).
 On error, the callback is called without arguments, otherwise it receives
       aioreq_pri $pri;
       add $grp aio_stat $wd, sub {
          return $grp->result () if $_[0];
          my $now = time;
          my $hash1 = join ":", (stat _)[0,1,3,7,9];
+         my $rdxflags = READDIR_DIRS_FIRST;
+         if ((stat _)[3] < 2) {
+            # at least one non-POSIX filesystem exists
+            # that returns useful DT_type values: btrfs,
+            # so optimise for this here by requesting dents
+            $rdxflags |= READDIR_DENTS;
+         }
          # read the directory entries
          aioreq_pri $pri;
-         add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {
+         add $grp aio_readdirx $wd, $rdxflags, sub {
-            my $entries = shift
+            my ($entries, $flags) = @_
                or return $grp->result ();
+            if ($rdxflags & READDIR_DENTS) {
+               # if we requested type values, see if we can use them directly.
+               # if there were any DT_UNKNOWN entries then we assume we
+               # don't know. alternatively, we could assume that if we get
+               # one DT_DIR, then all directories are indeed marked with
+               # DT_DIR, but this seems not required for btrfs, and this
+               # is basically the "btrfs can't get it's act together" code
+               # branch.
+               unless ($flags & READDIR_FOUND_UNKNOWN) {
+                  # now we have valid DT_ information for all entries,
+                  # so use it as an optimisation without further stat's.
+                  # they must also all be at the beginning of @$entries
+                  # by now.
+                  my $dirs;
+                  if (@$entries) {
+                     for (0 .. $#$entries) {
+                        if ($entries->[$_][1] != DT_DIR) {
+                           # splice out directories
+                           $dirs = [splice @$entries, 0, $_];
+                           last;
+                        }
+                     }
+                     # if we didn't find any non-dir, then all entries are dirs
+                     unless ($dirs) {
+                        ($dirs, $entries) = ($entries, []);
+                     }
+                  } else {
+                     # directory is empty, so there are no sbdirs
+                     $dirs = [];
+                  }
+                  # either splice'd the directories out or the dir was empty.
+                  # convert dents to filenames
+                  $_ = $_->[0] for @$dirs;
+                  $_ = $_->[0] for @$entries;
+                  return $grp->result ($dirs, $entries);
+               }
+               # cannot use, so return to our old ways
+               # by pretending we only scanned for names.
+               $_ = $_->[0] for @$entries;
+            }
             # stat the dir another time
             aioreq_pri $pri;
             add $grp aio_stat $wd, sub {
                my $hash2 = join ":", (stat _)[0,1,3,7,9];
    };
    $grp
 }
+=item aio_fcntl $fh, $cmd, $arg, $callback->($status)
+=item aio_ioctl $fh, $request, $buf, $callback->($status)
+These work just like the C<fcntl> and C<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 and can be used for normal C<ioctl>
+and C<fcntl> as well (missing ones are, as usual C<0>):
+C<F_DUPFD_CLOEXEC>,
+C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
+C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
+C<F_ADD_SEALS>, C<F_GET_SEALS>, C<F_SEAL_SEAL>, C<F_SEAL_SHRINK>, C<F_SEAL_GROW> and
+C<F_SEAL_WRITE>.
+C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
+C<FS_IOC_FIEMAP>.
+C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
+C<FS_IOC_GET_ENCRYPTION_PWSALT>, C<FS_IOC_GET_ENCRYPTION_POLICY>, C<FS_KEY_DESCRIPTOR_SIZE>.
+C<FS_SECRM_FL>, C<FS_UNRM_FL>, C<FS_COMPR_FL>, C<FS_SYNC_FL>, C<FS_IMMUTABLE_FL>,
+C<FS_APPEND_FL>, C<FS_NODUMP_FL>, C<FS_NOATIME_FL>, C<FS_DIRTY_FL>,
+C<FS_COMPRBLK_FL>, C<FS_NOCOMP_FL>, C<FS_ENCRYPT_FL>, C<FS_BTREE_FL>,
+C<FS_INDEX_FL>, C<FS_JOURNAL_DATA_FL>, C<FS_NOTAIL_FL>, C<FS_DIRSYNC_FL>, C<FS_TOPDIR_FL>,
+C<FS_FL_USER_MODIFIABLE>.
+C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
+C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
+C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
+C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
 =item aio_sync $callback->($status)
 Asynchronously call sync and call the callback when finished.
 =item aio_fsync $fh, $callback->($status)
    };
    $grp
 }
-=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
+=item 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 C<IO::AIO::mmap> function, although it also works on data
 scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the
 scalar must only be modified in-place while an aio operation is pending on
 It calls the C<msync> function of your OS, if available, with the memory
 area starting at C<$offset> in the string and ending C<$length> bytes
 later. If C<$length> is negative, counts from the end, and if C<$length>
 is C<undef>, then it goes till the end of the string. The flags can be
-a combination of C<IO::AIO::MS_ASYNC>, C<IO::AIO::MS_INVALIDATE> and
+either C<IO::AIO::MS_ASYNC> or C<IO::AIO::MS_SYNC>, plus an optional
-C<IO::AIO::MS_SYNC>.
+C<IO::AIO::MS_INVALIDATE>.
 =item 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
 =item aio_mlockall $flags, $callback->($status)
-Calls the C<mlockall> function with the given C<$flags> (a combination of
+Calls the C<mlockall> function with the given C<$flags> (a
-C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
+combination of C<IO::AIO::MCL_CURRENT>, C<IO::AIO::MCL_FUTURE> and
+C<IO::AIO::MCL_ONFAULT>).
 On systems that do not implement C<mlockall>, this function returns C<-1>
-and sets errno to C<ENOSYS>.
+and sets errno to C<ENOSYS>. Similarly, flag combinations not supported
+by the system result in a return value of C<-1> with errno being set to
+C<EINVAL>.
 Note that the corresponding C<munlockall> is synchronous and is
 documented under L<MISCELLANEOUS FUNCTIONS>.
 Example: asynchronously lock all current and future pages into memory.
 C<IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED>, C<IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED>,
 C<IO::AIO::FIEMAP_EXTENT_DATA_INLINE>, C<IO::AIO::FIEMAP_EXTENT_DATA_TAIL>,
 C<IO::AIO::FIEMAP_EXTENT_UNWRITTEN>, C<IO::AIO::FIEMAP_EXTENT_MERGED> or
 C<IO::AIO::FIEMAP_EXTENT_SHARED>.
-At the time of this writing (Linux 3.2), this requets is unreliable unless
+At the time of this writing (Linux 3.2), this request is unreliable unless
 C<$count> is C<undef>, as the kernel has all sorts of bugs preventing
-it to return all extents of a range for files with large number of
+it to return all extents of a range for files with a large number of
-extents. The code works around all these issues if C<$count> is undef.
+extents. The code (only) works around all these issues if C<$count> is
+C<undef>.
 =item 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
       aio_stat [$etcdir, "passwd"], sub {
          # yay
       };
    };
-That C<aio_wd> is a request and not a normal function shows that creating
+The fact that C<aio_wd> is a request and not a normal function shows that
-an IO::AIO::WD object is itself a potentially blocking operation, which is
+creating an IO::AIO::WD object is itself a potentially blocking operation,
-why it is done asynchronously.
+which is why it is done asynchronously.
 To stat the directory obtained with C<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 C<aio_realpath>) will always rely on
-string form of the pathname.
+the string form of the pathname.
 So this functionality is mainly useful to get some protection against
 C<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).
 passing C<undef> as working directory component of a pathname fails the
 request with C<ENOENT>, there is often no need for error checking in the
 C<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 C<fsync> instead.
 =item IO::AIO::CWD
-This is a compiletime constant (object) that represents the process
+This is a compile time 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. For
 example, these calls are functionally identical:
    aio_realpath $wd, sub {
       warn "path is $_[0]\n";
    };
+Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
+sometimes, fall back to using an absolue path.
 =head2 IO::AIO::REQ CLASS
 All non-aggregate C<aio_*> functions return an object of this class when
 called in non-void context.
 The default value for the limit is C<0>, but note that setting a feeder
 automatically bumps it up to C<2>.
 =back
 =head2 SUPPORT FUNCTIONS
 =head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
 =over 4
 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 (C<IO::AIO> uses an C<END> block which already calls
+this function on normal exits), or when you are merely using C<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
 =item IO::AIO::max_poll_reqs $nreqs
 =item IO::AIO::max_poll_time $seconds
 These set the maximum number of requests (default C<0>, meaning infinity)
               poll => 'r', nice => 1,
               cb => &IO::AIO::poll_cb);
 =back
 =head3 CONTROLLING THE NUMBER OF THREADS
 =over
 =item IO::AIO::min_parallel $nthreads
 longer exceeded.
 In other words, this setting does not enforce a queue limit, but can be
 used to make poll functions block if the limit is exceeded.
-This is a very bad function to use in interactive programs because it
+This is a bad function to use in interactive programs because it blocks,
-blocks, and a bad way to reduce concurrency because it is inexact: Better
+and a bad way to reduce concurrency because it is inexact. If you need to
+issue many requests without being able to call a poll function on demand,
-use an C<aio_group> together with a feed callback.
+it is better to use an C<aio_group> together with a feed callback.
-It's main use is in scripts without an event loop - when you want to stat
+Its main use is in scripts without an event loop - when you want to stat a
-a lot of files, you can write somehting like this:
+lot of files, you can write something like this:
    IO::AIO::max_outstanding 32;
    for my $path (...) {
       aio_stat $path , ...;
       IO::AIO::poll_cb;
    }
    IO::AIO::flush;
-The call to C<poll_cb> inside the loop will normally return instantly, but
+The call to C<poll_cb> inside the loop will normally return instantly,
-as soon as more thna C<32> reqeusts are in-flight, it will block until
+allowing the loop to progress, but as soon as more than C<32> requests
-some requests have been handled. This keeps the loop from pushing a large
+are in-flight, it will block until some requests have been handled. This
-number of C<aio_stat> requests onto the queue.
+keeps the loop from pushing a large number of C<aio_stat> requests onto
+the queue (which, with many paths to stat, can use up a lot of memory).
 The default value for C<max_outstanding> is very large, so there is no
 practical limit on the number of outstanding requests.
 =back
 =head3 STATISTICAL INFORMATION
 =over
 =item IO::AIO::nreqs
 Returns the number of requests currently in the pending state (executed,
 but not yet processed by poll_cb).
 =back
+=head3 SUBSECOND STAT TIME ACCESS
+Both C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<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
+C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> calls. Their return
+value is only meaningful after a successful C<stat>/C<lstat> call, or
+during/after a successful C<aio_stat>/C<aio_lstat> callback.
+This is similar to the L<Time::HiRes> C<stat> functions, but can return
+full resolution without rounding and work with standard perl C<stat>,
+alleviating the need to call the special C<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 C<0> is
+returned, so it is always safe to call these functions.
+=over 4
+=item $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 I<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 advantage of
+it). On systems where it isn't available, C<0> is currently returned, but
+this might change to C<undef> in a future version.
+=item ($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.
+=item $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 C<0> to C<999999999>.
+Note that no accessors are provided for access, modification and
+change times - you need to get those from C<stat _> if required (C<int
+IO::AIO::st_atime> and so on will I<not> generally give you the correct
+value).
+=item $seconds = IO::AIO::st_btimesec
+The (integral) seconds part of the file birth time, if available.
+=item ($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).
+=item $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 C<struct stat> (most BSDs at the time of this writing) and generally
+only to the root usert. If unsupported, C<0> is returned, but this might
+change to C<undef> in a future version.
+=back
+Example: print the high resolution modification time of F</etc>, using
+C<stat>, and C<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
 =head3 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 C<aio_*>
+counterpart.
 =over 4
+=item $retval = IO::AIO::fexecve $fh, $argv, $envp
+A more-or-less direct equivalent to the POSIX C<fexecve> functions, which
+allows you to specify the program to be executed via a file descriptor (or
+handle). Returns C<-1> and sets errno to C<ENOSYS> if not available.
+=item $numfd = IO::AIO::get_fdlimit
+Tries to find the current file descriptor limit and returns it, or
+C<undef> and sets C<$!> in case of an error. The limit is one larger than
+the highest valid file descriptor number.
+=item IO::AIO::min_fdlimit [$numfd]
+Try to increase the current file descriptor limit(s) to at least C<$numfd>
+by changing the soft or hard file descriptor resource limit. If C<$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
+C<IO::AIO::get_fdlimit>.
+If an error occurs, returns C<undef> and sets C<$!>, otherwise returns
+true.
 =item IO::AIO::sendfile $ofh, $ifh, $offset, $count
 Calls the C<eio_sendfile_sync> function, which is like C<aio_sendfile>,
 but is blocking (this makes most sense if you know the input data is
 =item IO::AIO::madvise $scalar, $offset, $len, $advice
 Simply calls the C<posix_madvise> function (see its
 manpage for details). The following advice constants are
 available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
-C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>.
+C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>,
+C<IO::AIO::MADV_DONTNEED>.
+If C<$offset> is negative, counts from the end. If C<$length> is negative,
+the remaining length of the C<$scalar> is used. If possible, C<$length>
+will be reduced to fit into the C<$scalar>.
 On systems that do not implement C<posix_madvise>, this function returns
 ENOSYS, otherwise the return value of C<posix_madvise>.
 =item IO::AIO::mprotect $scalar, $offset, $len, $protect
 Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
 $scalar (see its manpage for details). The following protect
 constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
 C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
+If C<$offset> is negative, counts from the end. If C<$length> is negative,
+the remaining length of the C<$scalar> is used. If possible, C<$length>
+will be reduced to fit into the C<$scalar>.
 On systems that do not implement C<mprotect>, this function returns
 ENOSYS, otherwise the return value of C<mprotect>.
 =item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
 Memory-maps a file (or anonymous memory range) and attaches it to the
 given C<$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, C<undef>
+the scalar first.
-The only operations allowed on the scalar are C<substr>/C<vec> that don't
+The only operations allowed on the mmapped scalar are C<substr>/C<vec>,
-change the string length, and most read-only operations such as copying it
+which don't change the string length, and most read-only operations such
-or searching it with regexes and so on.
+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 C<$scalar> is automatically removed
-when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or
+when the C<$scalar> is undef'd or destroyed, or when the C<IO::AIO::mmap>
-C<IO::AIO::munmap> functions are called.
+or C<IO::AIO::munmap> functions are called on it.
 This calls the C<mmap>(2) function internally. See your system's manual
 page for details on the C<$length>, C<$prot> and C<$flags> parameters.
 The C<$length> must be larger than zero and smaller than the actual
 filesize.
 C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>,
 C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
-C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or
+C<$flags> can be a combination of
-C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when
+C<IO::AIO::MAP_SHARED> or
-not available, the are defined as 0): C<IO::AIO::MAP_ANONYMOUS>
+C<IO::AIO::MAP_PRIVATE>,
+or a number of system-specific flags (when not available, the are C<0>):
-(which is set to C<MAP_ANON> if your system only provides this
+C<IO::AIO::MAP_ANONYMOUS> (which is set to C<MAP_ANON> if your system only provides this constant),
-constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>,
+C<IO::AIO::MAP_LOCKED>,
-C<IO::AIO::MAP_NORESERVE>, C<IO::AIO::MAP_POPULATE> or
+C<IO::AIO::MAP_NORESERVE>,
+C<IO::AIO::MAP_POPULATE>,
-C<IO::AIO::MAP_NONBLOCK>
+C<IO::AIO::MAP_NONBLOCK>,
+C<IO::AIO::MAP_FIXED>,
+C<IO::AIO::MAP_GROWSDOWN>,
+C<IO::AIO::MAP_32BIT>,
+C<IO::AIO::MAP_HUGETLB>,
+C<IO::AIO::MAP_STACK>,
+C<IO::AIO::MAP_FIXED_NOREPLACE>,
+C<IO::AIO::MAP_SHARED_VALIDATE>,
+C<IO::AIO::MAP_SYNC> or
+C<IO::AIO::MAP_UNINITIALIZED>.
 If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
 C<$offset> is the offset from the start of the file - it generally must be
 a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
 =item IO::AIO::munmap $scalar
 Removes a previous mmap and undefines the C<$scalar>.
+=item IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[, $new_address = 0]
+Calls the Linux-specific mremap(2) system call. The C<$scalar> must have
+been mapped by C<IO::AIO::mmap>, and C<$flags> must currently either be
+C<0> or C<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
+C<1>, otherwise it has the numerical value C<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";
+   }
+C<IO::AIO::MREMAP_FIXED> and the C<$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 C<$!> to C<ENOSYS>.
+=item IO::AIO::mlockall $flags
+Calls the C<eio_mlockall_sync> function, which is like C<aio_mlockall>,
+but is blocking.
 =item IO::AIO::munlock $scalar, $offset = 0, $length = undef
 Calls the C<munlock> function, undoing the effects of a previous
 C<aio_mlock> call (see its description for details).
 Calls the C<munlockall> function.
 On systems that do not implement C<munlockall>, this function returns
 ENOSYS, otherwise the return value of C<munlockall>.
+=item $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
+Uses the GNU/Linux C<accept4(2)> syscall, if available, to accept a socket
+and return the new file handle on success, or sets C<$!> and returns
+C<undef> on error.
+The remote name of the new socket will be stored in C<$sockaddr>, which
+will be extended to allow for at least C<$sockaddr_maxlen> octets. If the
+socket name does not fit into C<$sockaddr_maxlen> octets, this is signaled
+by returning a longer string in C<$sockaddr>, which might or might not be
+truncated.
+To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
+C<$sockaddr_maxlen>.
+The main reasons to use this syscall rather than portable C<accept(2)>
+are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
+flags and you can accept name-less sockets by specifying C<0> for
+C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
+C<accept>.
 =item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
 Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
 C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
 See the C<splice(2)> manpage for details.
 =item IO::AIO::tee $r_fh, $w_fh, $length, $flags
-Calls the GNU/Linux C<tee(2)> syscall, see it's manpage and the
+Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
 description for C<IO::AIO::splice> above for details.
+=item $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
+C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
+size on other systems, drop me a note.
+=item ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
+This is a direct interface to the Linux L<pipe2(2)> system call. If
+C<$flags> is missing or C<0>, then this should be the same as a call to
+perl's built-in C<pipe> function and create a new pipe, and works on
+systems that lack the pipe2 syscall. On win32, this case invokes C<_pipe
+(..., 4096, O_BINARY)>.
+If C<$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
+C<$flags> is non-zero, fails with C<ENOSYS>.
+Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
+time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
+C<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";
+=item $fh = IO::AIO::memfd_create $pathname[, $flags]
+This is a direct interface to the Linux L<memfd_create(2)> system
+call. The (unhelpful) default for C<$flags> is C<0>, but your default
+should be C<IO::AIO::MFD_CLOEXEC>.
+On success, the new memfd filehandle is returned, otherwise returns
+C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
+Please refer to L<memfd_create(2)> for more info on this call.
+The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
+C<IO::AIO::MFD_ALLOW_SEALING>, C<IO::AIO::MFD_HUGETLB>,
+C<IO::AIO::MFD_HUGETLB_2MB> and C<IO::AIO::MFD_HUGETLB_1GB>.
+Example: create a new memfd.
+   my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
+      or die "memfd_create: $!\n";
+=item $fh = IO::AIO::pidfd_open $pid[, $flags]
+This is an interface to the Linux L<pidfd_open(2)> system call. The
+default for C<$flags> is C<0>.
+On success, a new pidfd filehandle is returned (that is already set to
+close-on-exec), otherwise returns C<undef>. If the syscall is missing,
+fails with C<ENOSYS>.
+Example: open pid 6341 as pidfd.
+   my $fh = IO::AIO::pidfd_open 6341
+      or die "pidfd_open: $!\n";
+=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
+This is an interface to the Linux L<pidfd_send_signal> system call. The
+default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
+Returns the system call status.  If the syscall is missing, fails with
+C<ENOSYS>.
+When specified, C<$siginfo> must be a reference to a hash with one or more
+of the following members:
+=over
+=item code - the C<si_code> member
+=item pid - the C<si_pid> member
+=item uid - the C<si_uid> member
+=item value_int - the C<si_value.sival_int> member
+=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
+=back
+Example: send a SIGKILL to the specified process.
+   my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
+      and die "pidfd_send_signal: $!\n";
+Example: send a SIGKILL to the specified process with extra data.
+   my $status = IO::AIO::pidfd_send_signal $pidfh, 9,  { code => -1, value_int => 7 }
+      and die "pidfd_send_signal: $!\n";
+=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
+This is an interface to the Linux L<pidfd_getfd> system call. The default
+for C<$flags> is C<0>.
+On success, returns a dup'ed copy of the target file descriptor (specified
+as an integer) returned (that is already set to close-on-exec), otherwise
+returns C<undef>. If the syscall is missing, fails with C<ENOSYS>.
+Example: get a copy of standard error of another process and print soemthing to it.
+   my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
+      or die "pidfd_getfd: $!\n";
+   print $errfh "stderr\n";
+=item $fh = IO::AIO::eventfd [$initval, [$flags]]
+This is a direct interface to the Linux L<eventfd(2)> system call. The
+(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
+On success, the new eventfd filehandle is returned, otherwise returns
+C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
+Please refer to L<eventfd(2)> for more info on this call.
+The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
+C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
+Example: create a new eventfd filehandle:
+   $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
+      or die "eventfd: $!\n";
+=item $fh = IO::AIO::timerfd_create $clockid[, $flags]
+This is a direct interface to the Linux L<timerfd_create(2)> system
+call. The (unhelpful) default for C<$flags> is C<0>, but your default
+should be C<IO::AIO::TFD_CLOEXEC>.
+On success, the new timerfd filehandle is returned, otherwise returns
+C<undef>. If the timerfd_create syscall is missing, fails with C<ENOSYS>.
+Please refer to L<timerfd_create(2)> for more info on this call.
+The following C<$clockid> values are
+available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
+C<IO::AIO::CLOCK_CLOCK_BOOTTIME> (Linux 3.15)
+C<IO::AIO::CLOCK_CLOCK_REALTIME_ALARM> (Linux 3.11) and
+C<IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM> (Linux 3.11).
+The following C<$flags> values are available (Linux
+2.6.27): C<IO::AIO::TFD_NONBLOCK> and C<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;
+   }
+=item ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
+This is a direct interface to the Linux L<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, C<$new_interval> and C<$new_value>).
+On success, the current interval and value are returned (as per
+C<timerfd_gettime>). On failure, the empty list is returned.
+The following C<$flags> values are
+available: C<IO::AIO::TFD_TIMER_ABSTIME> and
+C<IO::AIO::TFD_TIMER_CANCEL_ON_SET>.
+See C<IO::AIO::timerfd_create> for a full example.
+=item ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
+This is a direct interface to the Linux L<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.
 =back
 =cut
 the process will result in undefined behaviour. Calling it at any time
 will also result in any undefined (by POSIX) behaviour.
 =back
+=head2 LINUX-SPECIFIC CALLS
+When a call is documented as "linux-specific" then this means it
+originated on GNU/Linux. C<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
+C<ENOSYS>.
 =head2 MEMORY USAGE
 Per-request usage:
 Each aio request uses - depending on your architecture - around 100-200
 temporary buffers, and each thread requires a stack and other data
 structures (usually around 16k-128k, depending on the OS).
 =head1 KNOWN BUGS
-Known bugs will be fixed in the next release.
+Known bugs will be fixed in the next release :)
+=head1 KNOWN ISSUES
+Calls that try to "import" foreign memory areas (such as C<IO::AIO::mmap>
+or C<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 C<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.
 =head1 SEE ALSO
 L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
-more natural syntax.
+more natural syntax and L<IO::FDPass> for file descriptor passing.
 =head1 AUTHOR
  Marc Lehmann <schmorp@schmorp.de>
  http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.240 by root, Mon Dec 17 06:18:39 2012 UTC vs. Revision 1.315 by root, Mon Sep 5 00:03:32 2022 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.240 by root, Mon Dec 17 06:18:39 2012 UTC vs.
Revision 1.315 by root, Mon Sep 5 00:03:32 2022 UTC