--- IO-AIO/README	2010/01/07 20:25:57	1.42
+++ IO-AIO/README	2010/01/10 23:44:02	1.43
@@ -26,29 +26,6 @@
      my $grp = aio_group sub { print "all stats done\n" };
      add $grp aio_stat "..." for ...;
 
-     # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
-     use AnyEvent::AIO;
-
-     # 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);
-
 DESCRIPTION
     This module implements asynchronous I/O using whatever means your
     operating system supports. It is implemented as an interface to "libeio"
@@ -170,6 +147,73 @@
         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
@@ -315,7 +359,7 @@
 
         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 a native sendfile cannot be found or it fails with "ENOSYS",
         "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK",
@@ -685,9 +729,10 @@
     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 Sys::Mmap or Mmap modules for details on
-        this, note that the scalar must only be modified in-place while an
-        aio operation is pending on it).
+        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
@@ -930,6 +975,30 @@
                       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
@@ -962,30 +1031,6 @@
                       poll => 'r', nice => 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;
-
    CONTROLLING THE NUMBER OF THREADS
     IO::AIO::min_parallel $nthreads
         Set the minimum number of AIO threads to $nthreads. The current
@@ -1096,6 +1141,102 @@
         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: