[ViewVC] Diff of: cvs/IO-AIO/README

Comparing IO-AIO/README (file contents):
Revision 1.20 by root, Tue Oct 31 00:45:41 2006 UTC vs.
Revision 1.43 by root, Sun Jan 10 23:44:02 2010 UTC

 SYNOPSIS
      use IO::AIO;
      aio_open "/etc/passwd", O_RDONLY, 0, sub {
-        my ($fh) = @_;
+        my $fh = shift
+           or die "/etc/passwd: $!";
         ...
      };
      aio_unlink "/tmp/file", sub { };
      $req->cancel; # cancel request if still in queue
      my $grp = aio_group sub { print "all stats done\n" };
      add $grp aio_stat "..." for ...;
-     # AnyEvent integration
-     open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
-     my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
-     # Event integration
-     Event->io (fd => IO::AIO::poll_fileno,
-                poll => 'r',
-                cb => \&IO::AIO::poll_cb);
-     # Glib/Gtk2 integration
-     add_watch Glib::IO IO::AIO::poll_fileno,
-               in => sub { IO::AIO::poll_cb; 1 };
-     # Tk integration
-     Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
-                               readable => \&IO::AIO::poll_cb);
-     # Danga::Socket integration
-     Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
-                                 \&IO::AIO::poll_cb);
 DESCRIPTION
     This module implements asynchronous I/O using whatever means your
-    operating system supports.
+    operating system supports. It is implemented as an interface to "libeio"
+    (<http://software.schmorp.de/pkg/libeio.html>).
     Asynchronous means that operations that can normally block your program
     (e.g. reading from disk) will be done asynchronously: the operation will
     still block, but you can do something else in the meantime. This is
     extremely useful for programs that need to stay interactive even when
     faster on a RAID volume or over NFS when you do a number of stat
     operations concurrently.
     While most of this works on all types of file descriptors (for example
     sockets), using these functions on file descriptors that support
-    nonblocking operation (again, sockets, pipes etc.) is very inefficient
+    nonblocking operation (again, sockets, pipes etc.) is very inefficient.
-    or might not work (aio_read fails on sockets/pipes/fifos). Use an event
-    loop for that (such as the Event module): IO::AIO will naturally fit
+    Use an event loop for that (such as the EV module): IO::AIO will
-    into such an event loop itself.
+    naturally fit into such an event loop itself.
     In this version, a number of threads are started that execute your
     requests and signal their completion. You don't need thread support in
     perl, and the threads created by this module will not be visible to
     perl. In the future, this module might make use of the native 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.
-    Although the module will work with in the presence of other (Perl-)
+    Although the module will work in the presence of other (Perl-) threads,
-    threads, it is currently not reentrant in any way, so use appropriate
+    it is currently not reentrant in any way, so use appropriate locking
-    locking yourself, always call "poll_cb" from within the same thread, or
+    yourself, always call "poll_cb" from within the same thread, or never
-    never call "poll_cb" (or other "aio_" functions) recursively.
+    call "poll_cb" (or other "aio_" functions) recursively.
   EXAMPLE
-    This is a simple example that uses the Event module and loads
+    This is a simple example that uses the EV module and loads /etc/passwd
-    /etc/passwd asynchronously:
+    asynchronously:
        use Fcntl;
-       use Event;
+       use EV;
        use IO::AIO;
-       # register the IO::AIO callback with Event
+       # register the IO::AIO callback with EV
-       Event->io (fd => IO::AIO::poll_fileno,
+       my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
-                  poll => 'r',
-                  cb => \&IO::AIO::poll_cb);
        # queue the request to open /etc/passwd
        aio_open "/etc/passwd", O_RDONLY, 0, sub {
-          my $fh = $_[0]
+          my $fh = shift
              or die "error while opening: $!";
           # stat'ing filehandles is generally non-blocking
           my $size = -s $fh;
              # file contents now in $contents
              print $contents;
              # exit event loop and program
-             Event::unloop;
+             EV::unloop;
           };
        };
        # possibly queue up other requests, or open GUI windows,
        # check for sockets etc. etc.
        # process events as long as there are some:
-       Event::loop;
+       EV::loop;
 REQUEST ANATOMY AND LIFETIME
     Every "aio_*" function creates a request. which is a C data structure
     not directly visible to Perl.
         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 of the most important functions
+    for quick reference. See the following sections for function-by-function
+    documentation.
+       aio_open $pathname, $flags, $mode, $callback->($fh)
+       aio_close $fh, $callback->($status)
+       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_truncate $fh_or_path, $offset, $callback->($status)
+       aio_chmod $fh_or_path, $mode, $callback->($status)
+       aio_unlink $pathname, $callback->($status)
+       aio_mknod $path, $mode, $dev, $callback->($status)
+       aio_link $srcpath, $dstpath, $callback->($status)
+       aio_symlink $srcpath, $dstpath, $callback->($status)
+       aio_readlink $path, $callback->($link)
+       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)
+          IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
+          IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
+       aio_load $path, $data, $callback->($status)
+       aio_copy $srcpath, $dstpath, $callback->($status)
+       aio_move $srcpath, $dstpath, $callback->($status)
+       aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
+       aio_rmtree $path, $callback->($status)
+       aio_sync $callback->($status)
+       aio_fsync $fh, $callback->($status)
+       aio_fdatasync $fh, $callback->($status)
+       aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
+       aio_pathsync $path, $callback->($status)
+       aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
+       aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $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::max_outstanding $maxreqs
+       IO::AIO::nreqs
+       IO::AIO::nready
+       IO::AIO::npending
+       IO::AIO::sendfile $ofh, $ifh, $offset, $count
+       IO::AIO::fadvise $fh, $offset, $len, $advice
+       IO::AIO::mlockall $flags
+       IO::AIO::munlockall
   AIO REQUEST FUNCTIONS
     All the "aio_*" calls are more or less thin wrappers around the syscall
     with the same name (sans "aio_"). The arguments are similar or
     identical, and they all accept an additional (and optional) $callback
     argument which must be a code reference. This code reference will get
     called with the syscall return code (e.g. most syscalls return -1 on
-    error, unlike perl, which usually delivers "false") as it's sole
+    error, unlike perl, which usually delivers "false") as its sole argument
-    argument when the given syscall has been executed asynchronously.
+    after the given syscall has been executed asynchronously.
     All functions expecting a filehandle keep a copy of the filehandle
     internally until the request has finished.
     All functions return request objects of type IO::AIO::REQ that allow
     the user environment, d) use Glib::filename_from_unicode on unicode
     filenames or e) use something else to ensure your scalar has the correct
     contents.
     This works, btw. independent of the internal UTF-8 bit, which IO::AIO
-    handles correctly wether it is set or not.
+    handles correctly whether it is set or not.
     $prev_pri = aioreq_pri [$pri]
         Returns the priority value that would be used for the next request
         and, if $pri is given, sets the priority for the next aio request.
         They are the same as used by "sysopen".
         Likewise, $mode specifies the mode of the newly created file, if it
         didn't exist and "O_CREAT" has been given, just like perl's
         "sysopen", except that it is mandatory (i.e. use 0 if you don't
-        create new files, and 0666 or 0777 if you do).
+        create new files, and 0666 or 0777 if you do). Note that the $mode
+        will be modified by the umask in effect then the request is being
+        executed, so better never change the umask.
         Example:
            aio_open "/etc/passwd", O_RDONLY, 0, sub {
               if ($_[0]) {
               }
            };
     aio_close $fh, $callback->($status)
         Asynchronously close a file and call the callback with the result
-        code. *WARNING:* although accepted, you should not pass in a perl
+        code.
-        filehandle here, as perl will likely close the file descriptor
-        another time when the filehandle is destroyed. Normally, you can
-        safely call perls "close" or just let filehandles go out of scope.
-        This is supposed to be a bug in the API, so that might change. It's
+        Unfortunately, you can't do this to perl. Perl *insists* very
-        therefore best to avoid this function.
+        strongly on closing the file descriptor associated with the
+        filehandle itself.
+        Therefore, "aio_close" will not close the filehandle - instead it
+        will use dup2 to overwrite the file descriptor with the write-end of
+        a pipe (the pipe fd will be created on demand and will be cached).
+        Or in other words: the file descriptor will be closed, but it will
+        not be free for reuse until the perl filehandle is closed.
     aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
     aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
-        Reads or writes "length" bytes from the specified "fh" and "offset"
+        Reads or writes $length bytes from or to the specified $fh and
-        into the scalar given by "data" and offset "dataoffset" and calls
+        $offset into the scalar given by $data and offset $dataoffset and
-        the callback without the actual number of bytes read (or -1 on
+        calls the callback without the actual number of bytes read (or -1 on
         error, just like the syscall).
+        "aio_read" will, like "sysread", shrink or grow the $data scalar to
+        offset plus the actual number of bytes read.
+        If $offset is undefined, then the current file descriptor offset
+        will be used (and updated), otherwise the file descriptor offset
+        will not be changed by these calls.
+        If $length is undefined in "aio_write", use the remaining length of
+        $data.
+        If $dataoffset is less than zero, it will be counted from the end of
+        $data.
         The $data scalar *MUST NOT* be modified in any way while the request
-        is outstanding. Modifying it can result in segfaults or WW3 (if the
+        is outstanding. Modifying it can result in segfaults or World War
-        necessary/optional hardware is installed).
+        III (if the necessary/optional hardware is installed).
         Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
         offset 0 within the scalar:
            aio_read $fh, 7, 15, $buffer, 0, sub {
         more than one "aio_sendfile" per $out_fh, as they will interfere
         with each other.
         This call tries to make use of a native "sendfile" syscall to
         provide zero-copy operation. For this to work, $out_fh should refer
-        to a socket, and $in_fh should refer to mmap'able file.
+        to a socket, and $in_fh should refer to an mmap'able file.
-        If the native sendfile call fails or is not implemented, it will be
+        If a native sendfile cannot be found or it fails with "ENOSYS",
+        "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK",
-        emulated, so you can call "aio_sendfile" on any type of filehandle
+        it will be emulated, so you can call "aio_sendfile" on any type of
-        regardless of the limitations of the operating system.
+        filehandle regardless of the limitations of the operating system.
         Please note, however, that "aio_sendfile" can read more bytes from
         $in_fh than are written, and there is no way to find out how many
         bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
         only provides the number of bytes written to $out_fh. Only if the
            aio_stat "/etc/passwd", sub {
               $_[0] and die "stat failed: $!";
               print "size is ", -s _, "\n";
            };
+    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 utimes(2) if available, otherwise
+        utime(2). If called on a file descriptor, uses 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_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 $path, $mode, $dev, $callback->($status)
     aio_rename $srcpath, $dstpath, $callback->($status)
         Asynchronously rename the object at $srcpath to $dstpath, just as
         rename(2) and call the callback with the result code.
+    aio_mkdir $pathname, $mode, $callback->($status)
+        Asynchronously mkdir (create) a directory and call the callback with
+        the result code. $mode will be modified by the umask at the time the
+        request is executed, so do not change your umask.
     aio_rmdir $pathname, $callback->($status)
         Asynchronously rmdir (delete) a directory and call the callback with
         the result code.
     aio_readdir $pathname, $callback->($entries)
         Unlike the POSIX call of the same name, "aio_readdir" reads an
         entire directory (i.e. opendir + readdir + closedir). The entries
         will not be sorted, and will NOT include the "." and ".." entries.
-        The callback a single argument which is either "undef" or an
+        The callback is passed a single argument which is either "undef" or
-        array-ref with the filenames.
+        an array-ref with the filenames.
+    aio_readdirx $pathname, $flags, $callback->($entries, $flags)
+        Quite similar to "aio_readdir", but the $flags argument allows to
+        tune behaviour and output format. In case of an error, $entries will
+        be "undef".
+        The flags are a combination of the following constants, ORed
+        together (the flags will also be passed to the callback, possibly
+        modified):
+        IO::AIO::READDIR_DENTS
+            When this flag is off, then the callback gets an arrayref with
+            of names only (as with "aio_readdir"), otherwise it gets an
+            arrayref with "[$name, $type, $inode]" arrayrefs, each
+            describing a single directory entry in more detail.
+            $name is the name of the entry.
+            $type is one of the "IO::AIO::DT_xxx" constants:
+            "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
+            "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
+            "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
+            "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
+            you need to know, you have to run stat yourself. Also, for speed
+            reasons, the $type scalars are read-only: you can not modify
+            them.
+            $inode is the inode number (which might not be exact on systems
+            with 64 bit inode numbers and 32 bit perls). This field has
+            unspecified content on systems that do not deliver the inode
+            information.
+        IO::AIO::READDIR_DIRS_FIRST
+            When this flag is set, then the names will be returned in an
+            order where likely directories come first. This is useful when
+            you need to quickly find directories, or you want to find all
+            directories while avoiding to stat() each entry.
+            If the system returns type information in readdir, then this is
+            used to find directories directly. Otherwise, likely directories
+            are files beginning with ".", or otherwise files with no dots,
+            of which files with short names are tried first.
+        IO::AIO::READDIR_STAT_ORDER
+            When this flag is set, then the names will be returned in an
+            order suitable for stat()'ing each one. That is, when you plan
+            to stat() all files in the given directory, then the returned
+            order will likely be fastest.
+            If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
+            specified, then the likely dirs come first, resulting in a less
+            optimal stat order.
+        IO::AIO::READDIR_FOUND_UNKNOWN
+            This flag should not be set when calling "aio_readdirx".
+            Instead, it is being set by "aio_readdirx", when any of the
+            $type's found were "IO::AIO::DT_UNKNOWN". The absense of this
+            flag therefore indicates that all $type's are known, which can
+            be used to speed up some algorithms.
+    aio_load $path, $data, $callback->($status)
+        This is a composite request that tries to fully load the given file
+        into memory. Status is the same as with aio_read.
     aio_copy $srcpath, $dstpath, $callback->($status)
         Try to copy the *file* (directories not supported as either source
         or destination) from $srcpath to $dstpath and call the callback with
-        the 0 (error) or -1 ok.
+        a status of 0 (ok) or -1 (error, see $!).
-        This is a composite request that it creates the destination file
+        This is a composite request that creates the destination file with
-        with mode 0200 and copies the contents of the source file into it
+        mode 0200 and copies the contents of the source file into it using
-        using "aio_sendfile", followed by restoring atime, mtime, access
+        "aio_sendfile", followed by restoring atime, mtime, access mode and
-        mode and uid/gid, in that order.
+        uid/gid, in that order.
         If an error occurs, the partial destination file will be unlinked,
         if possible, except when setting atime, mtime, access mode and
         uid/gid, where errors are being ignored.
     aio_move $srcpath, $dstpath, $callback->($status)
         Try to move the *file* (directories not supported as either source
         or destination) from $srcpath to $dstpath and call the callback with
-        the 0 (error) or -1 ok.
+        a status of 0 (ok) or -1 (error, see $!).
-        This is a composite request that tries to rename(2) the file first.
+        This is a composite request that tries to rename(2) the file first;
-        If rename files with "EXDEV", it copies the file with "aio_copy"
+        if rename fails with "EXDEV", it copies the file with "aio_copy"
-        and, if that is successful, unlinking the $srcpath.
+        and, if that is successful, unlinks the $srcpath.
     aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
         Scans a directory (similar to "aio_readdir") but additionally tries
         to efficiently separate the entries of directory $path into two sets
         of names, directories you can recurse into (directories), and ones
         Implementation notes.
         The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
         can.
+        If readdir returns file type information, then this is used directly
+        to find directories.
-        After reading the directory, the modification time, size etc. of the
+        Otherwise, after reading the directory, the modification time, size
-        directory before and after the readdir is checked, and if they match
+        etc. of the directory before and after the readdir is checked, and
-        (and isn't the current time), the link count will be used to decide
+        if they match (and isn't the current time), the link count will be
-        how many entries are directories (if >= 2). Otherwise, no knowledge
+        used to decide how many entries are directories (if >= 2).
-        of the number of subdirectories will be assumed.
+        Otherwise, no knowledge of the number of subdirectories will be
+        assumed.
-        Then entries will be sorted into likely directories (everything
+        Then entries will be sorted into likely directories a non-initial
-        without a non-initial dot currently) and likely non-directories
+        dot currently) and likely non-directories (see "aio_readdirx"). Then
-        (everything else). Then every entry plus an appended "/." will be
+        every entry plus an appended "/." will be "stat"'ed, likely
-        "stat"'ed, likely directories first. If that succeeds, it assumes
+        directories first, in order of their inode numbers. If that
-        that the entry is a directory or a symlink to directory (which will
+        succeeds, it assumes that the entry is a directory or a symlink to
-        be checked seperately). This is often faster than stat'ing the entry
+        directory (which will be checked seperately). This is often faster
-        itself because filesystems might detect the type of the entry
+        than stat'ing the entry itself because filesystems might detect the
-        without reading the inode data (e.g. ext2fs filetype feature).
+        type of the entry without reading the inode data (e.g. ext2fs
+        filetype feature), even on systems that cannot return the filetype
+        information on readdir.
         If the known number of directories (link count - 2) has been
         reached, the rest of the entries is assumed to be non-directories.
         This only works with certainty on POSIX (= UNIX) filesystems, which
         It will also likely work on non-POSIX filesystems with reduced
         efficiency as those tend to return 0 or 1 as link counts, which
         disables the directory counting heuristic.
+    aio_rmtree $path, $callback->($status)
+        Delete a directory tree starting (and including) $path, return the
+        status of the final "rmdir" only. This is a composite request that
+        uses "aio_scandir" to recurse into and rmdir directories, and unlink
+        everything else.
+    aio_sync $callback->($status)
+        Asynchronously call sync and call the callback when finished.
     aio_fsync $fh, $callback->($status)
         Asynchronously call fsync on the given filehandle and call the
         callback with the fsync result code.
     aio_fdatasync $fh, $callback->($status)
         Asynchronously call fdatasync on the given filehandle and call the
         callback with the fdatasync result code.
         If this call isn't available because your OS lacks it or it couldn't
         be detected, it will be emulated by calling "fsync" instead.
+    aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
+        Sync the data portion of the file specified by $offset and $length
+        to disk (but NOT the metadata), by calling the Linux-specific
+        sync_file_range call. If sync_file_range is not available or it
+        returns ENOSYS, then fdatasync or fsync is being substituted.
+        $flags can be a combination of
+        "IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
+        "IO::AIO::SYNC_FILE_RANGE_WRITE" and
+        "IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
+        manpage for details.
+    aio_pathsync $path, $callback->($status)
+        This request tries to open, fsync and close the given path. This is
+        a composite request intended to sync directories after directory
+        operations (E.g. rename). This might not work on all operating
+        systems or have any specific effect, but usually it makes sure that
+        directory changes get written to disc. It works for anything that
+        can be opened for read-only, not just directories.
+        Future versions of this function might fall back to other methods
+        when "fsync" on the directory fails (such as calling "sync").
+        Passes 0 when everything went ok, and -1 on error.
+    aio_msync $scalar, $offset = 0, $length = undef, flags = 0,
+    $callback->($status)
+        This is a rather advanced IO::AIO call, which only works on
+        mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
+        also works on data scalars managed by the Sys::Mmap or Mmap modules,
+        note that the scalar must only be modified in-place while an aio
+        operation is pending on it).
+        It calls the "msync" function of your OS, if available, with the
+        memory area starting at $offset in the string and ending $length
+        bytes later. If $length is negative, counts from the end, and if
+        $length is "undef", then it goes till the end of the string. The
+        flags can be a combination of "IO::AIO::MS_ASYNC",
+        "IO::AIO::MS_INVALIDATE" and "IO::AIO::MS_SYNC".
+    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.
+        It touches (reads or writes) all memory pages in the specified range
+        inside the scalar. All caveats and parameters are the same as for
+        "aio_msync", above, except for flags, which must be either 0 (which
+        reads all pages and ensures they are instantiated) or
+        "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading
+        and writing an octet from it, which dirties the page).
     aio_group $callback->(...)
         This is a very special aio request: Instead of doing something, it
         is a container for other aio requests, which is useful if you want
         to bundle many requests into a single, composite, request with a
     cancel $req
         Cancels the request, if possible. Has the effect of skipping
         execution when entering the execute state and skipping calling the
         callback when entering the the result state, but will leave the
-        request otherwise untouched. That means that requests that currently
+        request otherwise untouched (with the exception of readdir). That
-        execute will not be stopped and resources held by the request will
+        means that requests that currently execute will not be stopped and
-        not be freed prematurely.
+        resources held by the request will not be freed prematurely.
     cb $req $callback->(...)
         Replace (or simply set) the callback registered to the request.
   IO::AIO::GRP CLASS
        };
     This makes it very easy to create composite requests (see the source of
     "aio_move" for an application) that work and feel like simple requests.
-    * The IO::AIO::GRP objects will be cleaned up during calls to
+    *   The IO::AIO::GRP objects will be cleaned up during calls to
-    "IO::AIO::poll_cb", just like any other request.
+        "IO::AIO::poll_cb", just like any other request.
-    * They can be canceled like any other request. Canceling will cancel not
+    *   They can be canceled like any other request. Canceling will cancel
-    only the request itself, but also all requests it contains.
+        not only the request itself, but also all requests it contains.
-    * They can also can also be added to other IO::AIO::GRP objects.
+    *   They can also can also be added to other IO::AIO::GRP objects.
-    * You must not add requests to a group from within the group callback
+    *   You must not add requests to a group from within the group callback
-    (or any later time).
+        (or any later time).
     Their lifetime, simplified, looks like this: when they are empty, they
     will finish very quickly. If they contain only requests that are in the
     "done" state, they will also finish. Otherwise they will continue to
     exist.
-    That means after creating a group you have some time to add requests.
+    That means after creating a group you have some time to add requests
-    And in the callbacks of those requests, you can add further requests to
+    (precisely before the callback has been invoked, which is only done
-    the group. And only when all those requests have finished will the the
+    within the "poll_cb"). And in the callbacks of those requests, you can
-    group itself finish.
+    add further requests to the group. And only when all those requests have
+    finished will the the group itself finish.
     add $grp ...
     $grp->add (...)
         Add one or more requests to the group. Any type of IO::AIO::REQ can
         be added, including other groups, as long as you do not create
     $grp->cancel_subs
         Cancel all subrequests and clears any feeder, but not the group
         request itself. Useful when you queued a lot of events but got a
         result early.
+        The group request will finish normally (you cannot add requests to
+        the group).
     $grp->result (...)
         Set the result value(s) that will be passed to the group callback
-        when all subrequests have finished and set thre groups errno to the
+        when all subrequests have finished and set the groups errno to the
         current value of errno (just like calling "errno" without an error
         number). By default, no argument will be passed and errno is zero.
     $grp->errno ([$errno])
         Sets the group errno value to $errno, or the current value of errno
         does not impose any limits).
         If the feed does not queue more requests when called, it will be
         automatically removed from the group.
-        If the feed limit is 0, it will be set to 2 automatically.
+        If the feed limit is 0 when this method is called, it will be set to
+        2 automatically.
         Example:
            # stat all files in @files, but only ever use four aio requests concurrently:
         Sets the feeder limit for the group: The feeder will be called
         whenever the group contains less than this many requests.
         Setting the limit to 0 will pause the feeding process.
+        The default value for the limit is 0, but note that setting a feeder
+        automatically bumps it up to 2.
   SUPPORT FUNCTIONS
    EVENT PROCESSING AND EVENT LOOP INTEGRATION
     $fileno = IO::AIO::poll_fileno
         Return the *request result pipe file descriptor*. This filehandle
         must be polled for reading by some mechanism outside this module
-        (e.g. Event or select, see below or the SYNOPSIS). If the pipe
+        (e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If the
-        becomes readable you have to call "poll_cb" to check the results.
+        pipe becomes readable you have to call "poll_cb" to check the
+        results.
         See "poll_cb" for an example.
     IO::AIO::poll_cb
         Process some outstanding events on the result pipe. You have to call
-        this regularly. Returns the number of events processed. Returns
+        this regularly. Returns 0 if all events could be processed, or -1 if
-        immediately when no events are outstanding. The amount of events
+        it returned earlier for whatever reason. Returns immediately when no
+        events are outstanding. The amount of events processed depends on
-        processed depends on the settings of "IO::AIO::max_poll_req" and
+        the settings of "IO::AIO::max_poll_req" and
         "IO::AIO::max_poll_time".
         If not all requests were processed for whatever reason, the
-        filehandle will still be ready when "poll_cb" returns.
+        filehandle will still be ready when "poll_cb" returns, so normally
+        you don't have to do anything special to have it called later.
         Example: Install an Event watcher that automatically calls
-        IO::AIO::poll_cb with high priority:
+        IO::AIO::poll_cb with high priority (more examples can be found in
+        the SYNOPSIS section, at the top of this document):
            Event->io (fd => IO::AIO::poll_fileno,
                       poll => 'r', async => 1,
                       cb => \&IO::AIO::poll_cb);
+    IO::AIO::poll_wait
+        If there are any outstanding requests and none of them in the result
+        phase, wait till the result filehandle becomes ready for reading
+        (simply does a "select" on the filehandle. This is useful if you
+        want to synchronously wait for some requests to finish).
+        See "nreqs" for an example.
+    IO::AIO::poll
+        Waits until some requests have been handled.
+        Returns the number of requests processed, but is otherwise strictly
+        equivalent to:
+           IO::AIO::poll_wait, IO::AIO::poll_cb
+    IO::AIO::flush
+        Wait till all outstanding AIO requests have been handled.
+        Strictly equivalent to:
+           IO::AIO::poll_wait, IO::AIO::poll_cb
+              while IO::AIO::nreqs;
     IO::AIO::max_poll_reqs $nreqs
     IO::AIO::max_poll_time $seconds
         These set the maximum number of requests (default 0, meaning
         infinity) that are being processed by "IO::AIO::poll_cb" in one
            # use a low priority so other tasks have priority
            Event->io (fd => IO::AIO::poll_fileno,
                       poll => 'r', nice => 1,
                       cb => &IO::AIO::poll_cb);
-    IO::AIO::poll_wait
-        Wait till the result filehandle becomes ready for reading (simply
-        does a "select" on the filehandle. This is useful if you want to
-        synchronously wait for some requests to finish).
-        See "nreqs" for an example.
-    IO::AIO::poll
-        Waits until some requests have been handled.
-        Strictly equivalent to:
-           IO::AIO::poll_wait, IO::AIO::poll_cb
-              if IO::AIO::nreqs;
-    IO::AIO::flush
-        Wait till all outstanding AIO requests have been handled.
-        Strictly equivalent to:
-           IO::AIO::poll_wait, IO::AIO::poll_cb
-              while IO::AIO::nreqs;
    CONTROLLING THE NUMBER OF THREADS
     IO::AIO::min_parallel $nthreads
         Set the minimum number of AIO threads to $nthreads. The current
         default is 8, which means eight asynchronous operations can execute
         concurrently at any one time (the number of outstanding requests,
         The default is probably ok in most situations, especially if thread
         creation is fast. If thread creation is very slow on your system you
         might want to use larger values.
-    $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
+    IO::AIO::max_outstanding $maxreqs
         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 "aio_group" together with a feed callback.
-        Sets the maximum number of outstanding requests to $nreqs. If you to
+        Sets the maximum number of outstanding requests to $nreqs. If you do
         queue up more than this number of requests, the next call to the
         "poll_cb" (and "poll_some" and other functions calling "poll_cb")
         function will block until the limit is no longer exceeded.
         The default value is very large, so there is no practical limit on
         the number of outstanding requests.
         You can still queue as many requests as you want. Therefore,
-        "max_oustsanding" is mainly useful in simple scripts (with low
+        "max_outstanding" is mainly useful in simple scripts (with low
         values) or as a stop gap to shield against fatal memory overflow
         (with large values).
    STATISTICAL INFORMATION
     IO::AIO::nreqs
         executed).
     IO::AIO::npending
         Returns the number of requests currently in the pending state
         (executed, but not yet processed by poll_cb).
+   MISCELLANEOUS FUNCTIONS
+    IO::AIO implements some functions that might be useful, but are not
+    asynchronous.
+    IO::AIO::sendfile $ofh, $ifh, $offset, $count
+        Calls the "eio_sendfile_sync" function, which is like
+        "aio_sendfile", but is blocking (this makes most sense if you know
+        the input data is likely cached already and the output filehandle is
+        set to non-blocking operations).
+        Returns the number of bytes copied, or -1 on error.
+    IO::AIO::fadvise $fh, $offset, $len, $advice
+        Simply calls the "posix_fadvise" function (see it's manpage for
+        details). The following advice constants are avaiable:
+        "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
+        "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
+        "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
+        On systems that do not implement "posix_fadvise", this function
+        returns ENOSYS, otherwise the return value of "posix_fadvise".
+    IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
+        Memory-maps a file (or anonymous memory range) and attaches it to
+        the given $scalar, which will act like a string scalar.
+        The only operations allowed on the scalar are "substr"/"vec" that
+        don't change the string length, and most read-only operations such
+        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 $scalar is automatically removed
+        when the $scalar is destroyed, or when the "IO::AIO::mmap" or
+        "IO::AIO::munmap" functions are called.
+        This calls the "mmap"(2) function internally. See your system's
+        manual page for details on the $length, $prot and $flags parameters.
+        The $length must be larger than zero and smaller than the actual
+        filesize.
+        $prot is a combination of "IO::AIO::PROT_NONE",
+        "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
+        "IO::AIO::PROT_WRITE",
+        $flags can be a combination of "IO::AIO::MAP_SHARED" or
+        "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
+        not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS"
+        (which is set to "MAP_ANON" if your system only provides this
+        constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
+        "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or
+        "IO::AIO::MAP_NONBLOCK"
+        If $fh is "undef", then a file descriptor of -1 is passed.
+        $offset is the offset from the start of the file - it generally must
+        be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
+        Example:
+           use Digest::MD5;
+           use IO::AIO;
+           open my $fh, "<verybigfile"
+              or die "$!";
+           IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
+              or die "verybigfile: $!";
+           my $fast_md5 = md5 $data;
+    IO::AIO::munmap $scalar
+        Removes a previous mmap and undefines the $scalar.
+    IO::AIO::mlockall $flags
+        Calls the "mlockall" function with the given $flags (a combination
+        of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL__FUTURE").
+        On systems that do not implement "mlockall", this function returns
+        ENOSYS, otherwise the return value of "mlockall".
+    IO::AIO::munlockall
+        Calls the "munlockall" function.
+        On systems that do not implement "munlockall", this function returns
+        ENOSYS, otherwise the return value of "munlockall".
+EVENT LOOP INTEGRATION
+    It is recommended to use AnyEvent::AIO to integrate IO::AIO
+    automatically into many event loops:
+     # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
+     use AnyEvent::AIO;
+    You can also integrate IO::AIO manually into many event loops, here are
+    some examples of how to do this:
+     # EV integration
+     my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
+     # Event integration
+     Event->io (fd => IO::AIO::poll_fileno,
+                poll => 'r',
+                cb => \&IO::AIO::poll_cb);
+     # Glib/Gtk2 integration
+     add_watch Glib::IO IO::AIO::poll_fileno,
+               in => sub { IO::AIO::poll_cb; 1 };
+     # Tk integration
+     Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
+                               readable => \&IO::AIO::poll_cb);
+     # Danga::Socket integration
+     Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
+                                 \&IO::AIO::poll_cb);
   FORK BEHAVIOUR
     This module should do "the right thing" when the process using it forks:
     Before the fork, IO::AIO enters a quiescent state where no requests can
     bytes of memory. In addition, stat requests need a stat buffer (possibly
     a few hundred bytes), readdir requires a result buffer and so on. Perl
     scalars and other data passed into aio requests will also be locked and
     will consume memory till the request has entered the done state.
-    This is now awfully much, so queuing lots of requests is not usually a
+    This is not awfully much, so queuing lots of requests is not usually a
     problem.
     Per-thread usage:
     In the execution phase, some aio requests require more memory for
 KNOWN BUGS
     Known bugs will be fixed in the next release.
 SEE ALSO
-    Coro::AIO.
+    AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
+    more natural syntax.
 AUTHOR
      Marc Lehmann <schmorp@schmorp.de>
      http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.20 by root, Tue Oct 31 00:45:41 2006 UTC vs. Revision 1.43 by root, Sun Jan 10 23:44:02 2010 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.20 by root, Tue Oct 31 00:45:41 2006 UTC vs.
Revision 1.43 by root, Sun Jan 10 23:44:02 2010 UTC