[ViewVC] Diff of: cvs/IO-AIO/AIO.pm

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.63 by root, Mon Oct 23 00:34:36 2006 UTC vs.
Revision 1.71 by root, Tue Oct 24 11:57:30 2006 UTC

  };
  # 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
  my $grp = aio_group sub { print "all stats done\n" };
  add $grp aio_stat "..." for ...;
 This module implements asynchronous I/O using whatever means your
 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
+and signal their completion. You don't need thread support in perl, and
-perl, and the threads created by this module will not be visible to the
+the threads created by this module will not be visible to perl.  In the
-pthreads library. In the future, this module might make use of the native
+future, this module might make use of the native aio functions available
-aio functions available on many operating systems. However, they are often
+on many operating systems. However, they are often not well-supported
-not well-supported (Linux doesn't allow them on normal files currently,
+(Linux doesn't allow them on normal files currently, for example),
-for example), and they would only support aio_read and aio_write, so the
+and they would only support aio_read and aio_write, so the remaining
-remaining functionality would have to be implemented using threads anyway.
+functionality would have to be implemented using threads anyway.
-Although the module will work with in the presence of other threads, it is
+Although the module will work with in the presence of other threads,
-currently not reentrant, so use appropriate locking yourself, always call
+it is currently not reentrant in any way, so use appropriate locking
-C<poll_cb> from within the same thread, or never call C<poll_cb> (or other
+yourself, always call C<poll_cb> from within the same thread, or never
-C<aio_> functions) recursively.
+call C<poll_cb> (or other C<aio_> functions) recursively.
 =cut
 package IO::AIO;
 use base 'Exporter';
 BEGIN {
    our $VERSION = '2.0';
-   our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
+   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_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
-                    aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
+                     aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
-                    aio_group aio_nop);
+                     aio_group aio_nop);
-   our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
+   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';
    require XSLoader;
    XSLoader::load ("IO::AIO", $VERSION);
 environment, d) use Glib::filename_from_unicode on unicode filenames or e)
 use something else.
 =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
 created filehandle for the file.
       $_[0] > 0 or die "read error: $!";
       print "read $_[0] bytes: <$buffer>\n";
    };
 =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.
 The callback a single argument which is either C<undef> or an array-ref
 with the filenames.
 =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
 recurse into (everything else).
 [EXPERIMENTAL]
 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.
 Example:
 This is a special request - it does nothing in itself and is only used for
 side effects, such as when you want to add a dummy request to a group so
 that finishing the requests in the group depends on executing the given
 code.
+While this request does nothing, it still goes through the execution
+phase and still requires a worker thread. Thus, the callback will not
+be executed immediately but only after other requests in the queue have
+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
+like sleep and file handle readable/writable, the overhead this creates is
-is immense, so do not use this function except to put your application
+immense (it blocks a thread for a long time) so do not use this function
-under artificial I/O pressure.
+except to put your application under artificial I/O pressure.
 =back
 =head2 IO::AIO::REQ CLASS
 callback) and B<done> (request has reached the end of its lifetime and
 holds no resources anymore).
 =over 4
-=item $req->cancel
+=item cancel $req
 Cancels the request, if possible. Has the effect of skipping execution
 when entering the B<execute> state and skipping calling the callback when
 entering the the B<result> state, but will leave the request otherwise
 untouched. That means that requests that currently execute will not be
 stopped and resources held by the request will not be freed prematurely.
+=item cb $req $callback->(...)
+Replace (or simply set) the callback registered to the request.
 =back
 =head2 IO::AIO::GRP CLASS
 This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to
 group. And only when all those requests have finished will the the group
 itself finish.
 =over 4
+=item add $grp ...
 =item $grp->add (...)
-=item add $grp ...
 Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
 be added, including other groups, as long as you do not create circular
 dependencies.
 =item $grp->result (...)
 Set the result value(s) that will be passed to the group callback when all
 subrequests have finished. By default, no argument will be passed.
-=item $grp->set_feeder ($callback->($grp))
+=item feed $grp $callback->($grp)
 [VERY EXPERIMENTAL]
 Sets a feeder/generator on this group: every group can have an attached
 generator that generates requests if idle. The idea behind this is that,
 example, C<aio_scandir> might generate hundreds of thousands C<aio_stat>
 requests, delaying any later requests for a long time.
 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
-feeder will be called whenever there are few enough (see C<feeder_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 feeder can queue as many requests as it likes (i.e. C<add> does not
+The feed callback can queue as many requests as it likes (i.e. C<add> does
-impose any limits).
+not impose any limits).
-If the feeder does not queue more requests when called, it will be
+If the feed does not queue more requests when called, it will be
 automatically removed from the group.
-If the feeder limit is C<0>, it will be set to C<2> automatically.
+If the feed limit is C<0>, it will be set to C<2> automatically.
 Example:
    # stat all files in @files, but only ever use four aio requests concurrently:
    my $grp = aio_group sub { print "finished\n" };
-   $grp->feeder_limit (4);
+   limit $grp 4;
-   $grp->set_feeder (sub {
+   feed $grp sub {
       my $file = pop @files
          or return;
       add $grp aio_stat $file, sub { ... };
-   });
+   };
-=item $grp->feeder_limit ($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.
 Setting the limit to C<0> will pause the feeding process.
 Each thread needs a stack area which is usually around 16k, sometimes much
 larger, depending on the OS.
 =head1 SEE ALSO
-L<Coro>, L<Linux::AIO> (obsolete).
+L<Coro::AIO>.
 =head1 AUTHOR
  Marc Lehmann <schmorp@schmorp.de>
  http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.63 by root, Mon Oct 23 00:34:36 2006 UTC vs. Revision 1.71 by root, Tue Oct 24 11:57:30 2006 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.63 by root, Mon Oct 23 00:34:36 2006 UTC vs.
Revision 1.71 by root, Tue Oct 24 11:57:30 2006 UTC