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

Comparing IO-AIO/README (file contents):
Revision 1.25 by root, Mon Sep 24 19:28:50 2007 UTC vs.
Revision 1.28 by root, Sun Mar 30 06:31:49 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
+     # AnyEvent integration (EV, Event, Glib, Tk, urxvt, pureperl...)
      open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
      my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
+     # EV integration
+     my $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);
               }
            };
     aio_close $fh, $callback->($status)
         Asynchronously close a file and call the callback with the result
-        code. *WARNING:* although accepted, you should not pass in a perl
+        code.
-        filehandle here, as perl will likely close the file descriptor
-        another time when the filehandle is destroyed. Normally, you can
-        safely call perls "close" or just let filehandles go out of scope.
-        This is supposed to be a bug in the API, so that might change. It's
+        Unfortunately, you can't do this to perl. Perl *insists* very
-        therefore best to avoid this function.
+        strongly on closing the file descriptor associated with the
+        filehandle itself. Here is what aio_close will try:
+           1. dup()licate the fd
+           2. asynchronously close() the duplicated fd
+           3. dup()licate the fd once more
+           4. let perl close() the filehandle
+           5. asynchronously close the duplicated fd
+        The idea is that the first close() flushes stuff to disk that
+        closing an fd will flush, so when perl closes the fd, nothing much
+        will need to be flushed. The second async. close() will then flush
+        stuff to disk that closing the last fd to the file will flush.
+        Just FYI, SuSv3 has this to say on close:
+           All outstanding record locks owned by the process on the file
+           associated with the file descriptor shall be removed.
+           If fildes refers to a socket, close() shall cause the socket to be
+           destroyed. ... close() shall block for up to the current linger
+           interval until all data is transmitted.
+           [this actually sounds like a specification bug, but who knows]
+        And at least Linux additionally actually flushes stuff on every
+        close, even when the file itself is still open.
+        Sounds enourmously inefficient and complicated? Yes... please show
+        me how to nuke perl's fd out of existence...
     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

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.25 by root, Mon Sep 24 19:28:50 2007 UTC vs. Revision 1.28 by root, Sun Mar 30 06:31:49 2008 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.25 by root, Mon Sep 24 19:28:50 2007 UTC vs.
Revision 1.28 by root, Sun Mar 30 06:31:49 2008 UTC