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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.244 by root, Fri Jan 24 23:46:16 2014 UTC vs.
Revision 1.253 by root, Thu Jun 25 13:34:28 2015 UTC

 use common::sense;
 use base 'Exporter';
 BEGIN {
-   our $VERSION = '4.19';
+   our $VERSION = 4.32;
    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_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_allocate
    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)
 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
       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
 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 should work
+everywhere.
+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.244 by root, Fri Jan 24 23:46:16 2014 UTC vs. Revision 1.253 by root, Thu Jun 25 13:34:28 2015 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.244 by root, Fri Jan 24 23:46:16 2014 UTC vs.
Revision 1.253 by root, Thu Jun 25 13:34:28 2015 UTC