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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.241 by root, Fri Dec 28 07:33:41 2012 UTC vs.
Revision 1.260 by root, Sun May 1 17:19:39 2016 UTC

 =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.34;
    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)
 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
       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
    };
    $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.
 =item aio_sync $callback->($status)
 Asynchronously call sync and call the callback when finished.
 =item aio_fsync $fh, $callback->($status)
       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.
 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
 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.241 by root, Fri Dec 28 07:33:41 2012 UTC vs. Revision 1.260 by root, Sun May 1 17:19:39 2016 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.241 by root, Fri Dec 28 07:33:41 2012 UTC vs.
Revision 1.260 by root, Sun May 1 17:19:39 2016 UTC