--- IO-AIO/AIO.pm	2010/01/07 18:08:21	1.172
+++ IO-AIO/AIO.pm	2010/01/10 20:37:33	1.175
@@ -28,29 +28,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);
-
 =head1 DESCRIPTION
 
 This module implements asynchronous I/O using whatever means your
@@ -193,7 +170,7 @@
 use base 'Exporter';
 
 BEGIN {
-   our $VERSION = '3.4';
+   our $VERSION = '3.5';
 
    our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
@@ -221,6 +198,74 @@
 
 =head1 FUNCTIONS
 
+=head2 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
+
 =head2 AIO REQUEST FUNCTIONS
 
 All the C<aio_*> calls are more or less thin wrappers around the syscall
@@ -434,7 +479,7 @@
    };
 
 
-=item aio_statvfs  $fh_or_path, $callback->($statvfs)
+=item aio_statvfs $fh_or_path, $callback->($statvfs)
 
 Works like the POSIX C<statvfs> or C<fstatvfs> syscalls, depending on
 whether a file handle or path was passed.
@@ -1314,6 +1359,33 @@
               poll => 'r', async => 1,
               cb => \&IO::AIO::poll_cb);
 
+=item 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 C<select> on the filehandle. This is useful if you want to
+synchronously wait for some requests to finish).
+
+See C<nreqs> for an example.
+
+=item 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
+
+=item 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;
+
 =item IO::AIO::max_poll_reqs $nreqs
 
 =item IO::AIO::max_poll_time $seconds
@@ -1347,33 +1419,6 @@
               poll => 'r', nice => 1,
               cb => &IO::AIO::poll_cb);
 
-=item 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 C<select> on the filehandle. This is useful if you want to
-synchronously wait for some requests to finish).
-
-See C<nreqs> for an example.
-
-=item 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
-
-=item 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;
-
 =back
 
 =head3 CONTROLLING THE NUMBER OF THREADS
@@ -1502,6 +1547,21 @@
 On systems that do not implement C<posix_fadvise>, this function returns
 ENOSYS, otherwise the return value of C<posix_fadvise>.
 
+=item IO::AIO::mlockall $flags
+
+Calls the C<mlockall> function with the given C<$flags> (a combination of
+C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>).
+
+On systems that do not implement C<mlockall>, this function returns
+ENOSYS, otherwise the return value of C<mlockall>.
+
+=item IO::AIO::munlockall
+
+Calls the C<munlockall> function.
+
+On systems that do not implement C<munlockall>, this function returns
+ENOSYS, otherwise the return value of C<munlockall>.
+
 =back
 
 =cut
@@ -1512,6 +1572,37 @@
 
 1;
 
+=head1 EVENT LOOP INTEGRATION
+
+It is recommended to use L<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);
+
 =head2 FORK BEHAVIOUR
 
 This module should do "the right thing" when the process using it forks: