IO-AIO
view release on metacpan or search on metacpan
Every "aio_*" function creates a request. which is a C data structure
not directly visible to Perl.
If called in non-void context, every request function returns a Perl
object representing the request. In void context, nothing is returned,
which saves a bit of memory.
The perl object is a fairly standard ref-to-hash object. The hash
contents are not used by IO::AIO so you are free to store anything you
like in it.
During their existance, aio requests travel through the following
states, in order:
ready
Immediately after a request is created it is put into the ready
state, waiting for a thread to execute it.
execute
A thread has accepted the request for processing and is currently
executing it (e.g. blocking in read).
pending
The request has been executed and is waiting for result processing.
While request submission and execution is fully asynchronous, result
processing is not and relies on the perl interpreter calling
"poll_cb" (or another function with the same effect).
result
The request results are processed synchronously by "poll_cb".
The "poll_cb" function will process all outstanding aio requests by
calling their callbacks, freeing memory associated with them and
managing any groups they are contained in.
done
Request has reached the end of its lifetime and holds no resources
anymore (except possibly for the Perl object, but its connection to
the actual aio request is severed and calling its methods will
either do nothing or result in a runtime error).
FUNCTIONS
QUICK OVERVIEW
This section simply lists the prototypes most of the functions for quick
reference. See the following sections for function-by-function
documentation.
aio_wd $pathname, $callback->($wd)
aio_open $pathname, $flags, $mode, $callback->($fh)
aio_close $fh, $callback->($status)
aio_seek $fh,$offset,$whence, $callback->($offs)
aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
aio_readahead $fh,$offset,$length, $callback->($retval)
aio_stat $fh_or_path, $callback->($status)
aio_lstat $fh, $callback->($status)
aio_statvfs $fh_or_path, $callback->($statvfs)
aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
aio_chown $fh_or_path, $uid, $gid, $callback->($status)
aio_chmod $fh_or_path, $mode, $callback->($status)
aio_truncate $fh_or_path, $offset, $callback->($status)
aio_allocate $fh, $mode, $offset, $len, $callback->($status)
aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
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->($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
IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
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 = 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->()
$prev_pri = aioreq_pri [$pri]
aioreq_nice $pri_adjust
IO::AIO::poll_wait
IO::AIO::poll_cb
IO::AIO::poll
IO::AIO::flush
IO::AIO::max_poll_reqs $nreqs
IO::AIO::max_poll_time $seconds
IO::AIO::min_parallel $nthreads
IO::AIO::max_parallel $nthreads
IO::AIO::max_idle $nthreads
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
aio_statvfs $fh_or_path, $callback->($statvfs)
Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
whether a file handle or path was passed.
On success, the callback is passed a hash reference with the
following members: "bsize", "frsize", "blocks", "bfree", "bavail",
"files", "ffree", "favail", "fsid", "flag" and "namemax". On
failure, "undef" is passed.
The following POSIX IO::AIO::ST_* constants are defined: "ST_RDONLY"
and "ST_NOSUID".
The following non-POSIX IO::AIO::ST_* flag masks are defined to
their correct value when available, or to 0 on systems that do not
support them: "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
"ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
"ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
Example: stat "/wd" and dump out the data if successful.
aio_statvfs "/wd", sub {
my $f = $_[0]
or die "statvfs: $!";
use Data::Dumper;
say Dumper $f;
};
# result:
{
bsize => 1024,
bfree => 4333064312,
blocks => 10253828096,
files => 2050765568,
flag => 4096,
favail => 2042092649,
bavail => 4333064312,
ffree => 2042092649,
namemax => 255,
frsize => 1024,
fsid => 1810
}
aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
Works like perl's "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 utimensat(2) or utimes(2) if
available, otherwise utime(2). If called on a file descriptor, uses
futimens(2) 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;
# set atime to current time and mtime to beginning of the epoch:
aio_utime "path", time, undef; # undef==0
aio_chown $fh_or_path, $uid, $gid, $callback->($status)
Works like perl's "chown" function, except that "undef" for either
$uid or $gid is being interpreted as "do not change" (but -1 can
also be used).
Examples:
# same as "chown root path" in the shell:
aio_chown "path", 0, -1;
# same as above:
aio_chown "path", 0, undef;
aio_truncate $fh_or_path, $offset, $callback->($status)
Works like truncate(2) or ftruncate(2).
aio_allocate $fh, $mode, $offset, $len, $callback->($status)
Allocates or frees disk space according to the $mode argument. See
the linux "fallocate" documentation for details.
$mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
(without leaving a hole), "FALLOC_FL_ZERO_RANGE", to zero a range,
"FALLOC_FL_INSERT_RANGE" to insert a range and
"FALLOC_FL_UNSHARE_RANGE" to unshare shared blocks (see your
fallocate(2) manpage).
The file system block size used by "fallocate" is presumably the
"f_bsize" returned by "statvfs", but different filesystems and
filetypes can dictate other limitations.
If "fallocate" isn't available or cannot be emulated (currently no
emulation will be attempted), passes -1 and sets $! to "ENOSYS".
aio_chmod $fh_or_path, $mode, $callback->($status)
Works like perl's "chmod" function.
aio_unlink $pathname, $callback->($status)
Asynchronously unlink (delete) a file and call the callback with the
result code.
aio_mknod $pathname, $mode, $dev, $callback->($status)
[EXPERIMENTAL]
Asynchronously create a device node (or fifo). See mknod(2).
The only (POSIX-) portable way of calling this function is:
aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
See "aio_stat" for info about some potentially helpful extra
constants and functions.
aio_link $srcpath, $dstpath, $callback->($status)
Asynchronously create a new link to the existing object at $srcpath
at the path $dstpath and call the callback with the result code.
aio_symlink $srcpath, $dstpath, $callback->($status)
Asynchronously create a new symbolic link to the existing object at
$srcpath at the path $dstpath and call the callback with the result
code.
aio_readlink $pathname, $callback->($link)
Asynchronously read the symlink specified by $path and pass it to
the callback. If an error occurs, nothing or undef gets passed to
the callback.
aio_realpath $pathname, $callback->($path)
Asynchronously make the path absolute and resolve any symlinks in
( run in 0.859 second using v1.01-cache-2.11-cpan-71847e10f99 )