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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.266 by root, Tue Aug 9 11:37:53 2016 UTC vs.
Revision 1.276 by root, Fri Sep 22 05:24:41 2017 UTC

 use common::sense;
 use base 'Exporter';
 BEGIN {
-   our $VERSION = 4.34;
+   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_fcntl aio_ioctl
                      aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
                      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_wd);
    aio_link $srcpath, $dstpath, $callback->($status)
    aio_symlink $srcpath, $dstpath, $callback->($status)
    aio_readlink $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_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::min_fdlimit $nfd;
    IO::AIO::sendfile $ofh, $ifh, $offset, $count
    IO::AIO::fadvise $fh, $offset, $len, $advice
    IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
    IO::AIO::munmap $scalar
 =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 with 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.
 C<$mode> is usually C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> to allocate
 space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE>,
 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
+(without leaving a hole), C<FALLOC_FL_ZERO_RANGE>, to zero a range,
-your L<fallocate(2)> manpage).
+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>.
 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
 =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.
 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<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<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
 C<FS_IOC_FIEMAP>.
    };
    $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.
 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.
 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:
+a lot of files, you can write something like this:
    IO::AIO::max_outstanding 32;
    for my $path (...) {
       aio_stat $path , ...;
 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 $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_FREE>.
+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

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.266 by root, Tue Aug 9 11:37:53 2016 UTC vs. Revision 1.276 by root, Fri Sep 22 05:24:41 2017 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.266 by root, Tue Aug 9 11:37:53 2016 UTC vs.
Revision 1.276 by root, Fri Sep 22 05:24:41 2017 UTC