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

Comparing IO-AIO/README (file contents):
Revision 1.26 by root, Thu Oct 4 12:50:35 2007 UTC vs.
Revision 1.31 by root, Thu May 29 03:35:03 2008 UTC

      $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 (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
+     use AnyEvent::AIO;
-     # AnyEvent integration
+     # EV integration
-     open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
+     my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
-     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);
     aio_close $fh, $callback->($status)
         Asynchronously close a file and call the callback with the result
         code.
-        Unlike the other functions operating on files, this function uses
+        Unfortunately, you can't do this to perl. Perl *insists* very
-        the PerlIO layer to close the filehandle. The reason is that the
+        strongly on closing the file descriptor associated with the
-        PerlIO API insists on closing the underlying fd itself, no matter
+        filehandle itself.
-        what, and doesn't allow modifications to the fd. Unfortunately, it
-        is not clear that you can call PerlIO from different threads
-        (actually, its quite clear that this won't work in some cases), so
-        while it likely works perfectly with simple file handles (such as
-        the ones created by "aio_open") it might fail in interesting ways
-        for others.
-        Having said that, aio_close tries to clean up the filehandle as much
+        Therefore, "aio_close" will not close the filehandle - instead it
-        as possible before handing it to an io thread, and generally does
+        will use dup2 to overwrite the file descriptor with the write-end of
-        work.
+        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
         into the scalar given by $data and offset $dataoffset and calls the
         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_pathsync $path, $callback->($status)
+        This request tries to open, fsync and close the given path. This is
+        a composite request intended tosync 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.
+        Passes 0 when everything went ok, and -1 on error.
     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
        };
     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.
         request itself. Useful when you queued a lot of events but got a
         result early.
     $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
         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:
            Event->io (fd => IO::AIO::poll_fileno,
         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 do
         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
 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.26 by root, Thu Oct 4 12:50:35 2007 UTC vs. Revision 1.31 by root, Thu May 29 03:35:03 2008 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.26 by root, Thu Oct 4 12:50:35 2007 UTC vs.
Revision 1.31 by root, Thu May 29 03:35:03 2008 UTC