--- IO-AIO/AIO.pm	2006/10/23 14:49:51	1.65
+++ IO-AIO/AIO.pm	2006/10/24 11:57:30	1.71
@@ -20,6 +20,7 @@
  # version 2+ has request and group objects
  use IO::AIO 2;
 
+ aioreq_pri 4; # give next request a very high priority
  my $req = aio_unlink "/tmp/file", sub { };
  $req->cancel; # cancel request if still in queue
 
@@ -53,18 +54,18 @@
 operating system supports.
 
 Currently, a number of threads are started that execute your read/writes
-and signal their completion. You don't need thread support in your libc or
-perl, and the threads created by this module will not be visible to the
-pthreads library. In the future, this module might make use of the native
-aio functions available on many operating systems. However, they are often
-not well-supported (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 threads, it is
-currently not reentrant, so use appropriate locking yourself, always call
-C<poll_cb> from within the same thread, or never call C<poll_cb> (or other
-C<aio_> functions) recursively.
+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 functions available
+on many operating systems. However, they are often not well-supported
+(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 threads,
+it is currently not reentrant in any way, so use appropriate locking
+yourself, always call C<poll_cb> from within the same thread, or never
+call C<poll_cb> (or other C<aio_> functions) recursively.
 
 =cut
 
@@ -78,11 +79,13 @@
 BEGIN {
    our $VERSION = '2.0';
 
-   our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
-                    aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
-                    aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
-                    aio_group aio_nop);
-   our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
+   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_scandir aio_symlink
+                     aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
+                     aio_group aio_nop);
+   our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
+   our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
+                       min_parallel max_parallel max_outstanding nreqs);
 
    @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
 
@@ -123,6 +126,34 @@
 
 =over 4
 
+=item aioreq_pri $pri
+
+Sets the priority for the next aio request. The default priority
+is C<0>, the minimum and maximum priorities are C<-4> and C<4>,
+respectively. Requests with higher priority will be serviced first.
+
+The priority will be reset to C<0> after each call to one of the C<aio_>
+functions.
+
+Example: open a file with low priority, then read something from it with
+higher priority so the read request is serviced before other low priority
+open requests (potentially spamming the cache):
+
+   aioreq_pri -3;
+   aio_open ..., sub {
+      return unless $_[0];
+
+      aioreq_pri -2;
+      aio_read $_[0], ..., sub {
+         ...
+      };
+   };
+
+=item aioreq_nice $pri_adjust
+
+Similar to C<aioreq_pri>, but subtracts the given value from the current
+priority, so effects are cumulative.
+
 =item aio_open $pathname, $flags, $mode, $callback->($fh)
 
 Asynchronously open or create a file and call the callback with a newly
@@ -184,8 +215,6 @@
 
 =item aio_move $srcpath, $dstpath, $callback->($status)
 
-[EXPERIMENTAL due to internal aio_group use]
-
 Try to move the I<file> (directories not supported as either source or
 destination) from C<$srcpath> to C<$dstpath> and call the callback with
 the C<0> (error) or C<-1> ok.
@@ -347,8 +376,6 @@
 
 =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
 
-[EXPERIMENTAL due to internal aio_group use]
-
 Scans a directory (similar to C<aio_readdir>) but additionally tries to
 separate the entries of directory C<$path> into two sets of names, ones
 you can recurse into (directories or links to them), and ones you cannot
@@ -519,7 +546,8 @@
 
 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.
+many requests into a single, composite, request with a definite callback
+and the ability to cancel the whole request with its subrequests.
 
 Returns an object of class L<IO::AIO::GRP>. See its documentation below
 for more info.
@@ -548,15 +576,15 @@
 entered their execution phase. This can be used to measure request
 latency.
 
-=item IO::AIO::aio_sleep $fractional_seconds, $callback->()  *NOT EXPORTED*
+=item IO::AIO::aio_busy $fractional_seconds, $callback->()  *NOT EXPORTED*
 
 Mainly used for debugging and benchmarking, this aio request puts one of
 the request workers to sleep for the given time.
 
 While it is theoretically handy to have simple I/O scheduling requests
-like sleep and file handle readable/writable, the overhead this creates
-is immense, so do not use this function except to put your application
-under artificial I/O pressure.
+like sleep and file handle readable/writable, the overhead this creates is
+immense (it blocks a thread for a long time) so do not use this function
+except to put your application under artificial I/O pressure.
 
 =back
 
@@ -681,12 +709,12 @@
 
 To avoid this, and allow incremental generation of requests, you can
 instead a group and set a feeder on it that generates those requests. The
-feed callback will be called whenever there are few enough (see C<feed_limit>,
+feed callback will be called whenever there are few enough (see C<limit>,
 below) requests active in the group itself and is expected to queue more
 requests.
 
-The feed can queue as many requests as it likes (i.e. C<add> does not
-impose any limits).
+The feed callback can queue as many requests as it likes (i.e. C<add> does
+not impose any limits).
 
 If the feed does not queue more requests when called, it will be
 automatically removed from the group.
@@ -698,7 +726,7 @@
    # stat all files in @files, but only ever use four aio requests concurrently:
 
    my $grp = aio_group sub { print "finished\n" };
-   feed_limit $grp 4;
+   limit $grp 4;
    feed $grp sub {
       my $file = pop @files
          or return;
@@ -706,7 +734,7 @@
       add $grp aio_stat $file, sub { ... };
    };
 
-=item feed_limit $grp $num
+=item limit $grp $num
 
 Sets the feeder limit for the group: The feeder will be called whenever
 the group contains less than this many requests.
@@ -886,7 +914,7 @@
 
 =head1 SEE ALSO
 
-L<Coro>, L<Linux::AIO> (obsolete).
+L<Coro::AIO>.
 
 =head1 AUTHOR