[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.268 by root, Tue May 30 22:45:52 2017 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.35;
    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_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_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_mkdir $pathname, $mode, $callback->($status)
    aio_rmdir $pathname, $callback->($status)
    aio_readdir $pathname, $callback->($entries)
    aio_readdirx $pathname, $flags, $callback->($entries, $flags)
    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->()
 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>, and C<O_TTY_INIT>.
 =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)
       namemax => 255,
       frsize  => 1024,
       fsid    => 1810
    }
-Here is a (likely partial) list of fsid values used by Linux - it is safe
+Here is a (likely partial - send me updates!) list of fsid values used by
-to hardcode these when the $^O is C<linux>:
+Linux - it is safe to hardcode these when C<$^O> is C<linux>:
    0x0000adf5 adfs
    0x0000adff affs
    0x5346414f afs
    0x09041934 anon-inode filesystem
    0x00001373 devfs
    0x00001cd1 devpts
    0x0000f15f ecryptfs
    0x00414a53 efs
    0x0000137d ext
-   0x0000ef53 ext2/ext3
+   0x0000ef53 ext2/ext3/ext4
    0x0000ef51 ext2
+   0xf2f52010 f2fs
    0x00004006 fat
    0x65735546 fuseblk
    0x65735543 fusectl
    0x0bad1dea futexfs
    0x01161970 gfs2
    0x47504653 gpfs
    0x00004244 hfs
    0xf995e849 hpfs
+   0x00c0ffee hostfs
    0x958458f6 hugetlbfs
    0x2bad1dea inotifyfs
    0x00009660 isofs
    0x000072b6 jffs2
    0x3153464a jfs
    0x00009fa1 openprom
    0x7461636F ocfs2
    0x00009fa0 proc
    0x6165676c pstorefs
    0x0000002f qnx4
+   0x68191122 qnx6
    0x858458f6 ramfs
    0x52654973 reiserfs
    0x00007275 romfs
    0x67596969 rpc_pipefs
    0x73636673 securityfs
 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) and C<FALLOC_FL_ZERO_RANGE>, to zero a range (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>.
 If C<fallocate> isn't available or cannot be emulated (currently no
 =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_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
    };
    $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 (missing ones are, as usual C<0>):
+C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
+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.
       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
 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
 current working directory.
    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.
 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 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 lot of files, you can write somehting like this:
    IO::AIO::max_outstanding 32;
    for my $path (...) {
 =back
 =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 IO::AIO::sendfile $ofh, $ifh, $offset, $count
 =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>,
+C<IO::AIO::MADV_FREE>.
 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
 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> or
+C<IO::AIO::MAP_STACK>.
 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>.
 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.
 =back
 =cut

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.268 by root, Tue May 30 22:45:52 2017 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.268 by root, Tue May 30 22:45:52 2017 UTC