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

Comparing IO-AIO/README (file contents):
Revision 1.37 by root, Fri Jun 12 16:55:17 2009 UTC vs.
Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC

      # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
      use AnyEvent::AIO;
      # EV integration
-     my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
+     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);
      Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
                                  \&IO::AIO::poll_cb);
 DESCRIPTION
     This module implements asynchronous I/O using whatever means your
-    operating system supports.
+    operating system supports. It is implemented as an interface to "libeio"
+    (<http://software.schmorp.de/pkg/libeio.html>).
     Asynchronous means that operations that can normally block your program
     (e.g. reading from disk) will be done asynchronously: the operation will
     still block, but you can do something else in the meantime. This is
     extremely useful for programs that need to stay interactive even when
     operations concurrently.
     While most of this works on all types of file descriptors (for example
     sockets), using these functions on file descriptors that support
     nonblocking operation (again, sockets, pipes etc.) is very inefficient.
-    Use an event loop for that (such as the Event module): IO::AIO will
+    Use an event loop for that (such as the EV module): IO::AIO will
     naturally fit into such an event loop itself.
     In this version, a number of threads are started that execute your
     requests and signal their completion. You don't need thread support in
     perl, and the threads created by this module will not be visible to
     it is currently not reentrant in any way, so use appropriate locking
     yourself, always call "poll_cb" from within the same thread, or never
     call "poll_cb" (or other "aio_" functions) recursively.
   EXAMPLE
-    This is a simple example that uses the Event module and loads
+    This is a simple example that uses the EV module and loads /etc/passwd
-    /etc/passwd asynchronously:
+    asynchronously:
        use Fcntl;
-       use Event;
+       use EV;
        use IO::AIO;
-       # register the IO::AIO callback with Event
+       # register the IO::AIO callback with EV
-       Event->io (fd => IO::AIO::poll_fileno,
+       my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
-                  poll => 'r',
-                  cb => \&IO::AIO::poll_cb);
        # queue the request to open /etc/passwd
        aio_open "/etc/passwd", O_RDONLY, 0, sub {
           my $fh = shift
              or die "error while opening: $!";
              # file contents now in $contents
              print $contents;
              # exit event loop and program
-             Event::unloop;
+             EV::unloop;
           };
        };
        # possibly queue up other requests, or open GUI windows,
        # check for sockets etc. etc.
        # process events as long as there are some:
-       Event::loop;
+       EV::loop;
 REQUEST ANATOMY AND LIFETIME
     Every "aio_*" function creates a request. which is a C data structure
     not directly visible to Perl.
             you need to know, you have to run stat yourself. Also, for speed
             reasons, the $type scalars are read-only: you can not modify
             them.
             $inode is the inode number (which might not be exact on systems
-            with 64 bit inode numbers and 32 bit perls). On systems that do
+            with 64 bit inode numbers and 32 bit perls). This field has
-            not deliver the inode information, this will always be zero.
+            unspecified content on systems that do not deliver the inode
+            information.
         IO::AIO::READDIR_DIRS_FIRST
             When this flag is set, then the names will be returned in an
             order where likely directories come first. This is useful when
             you need to quickly find directories, or you want to find all
         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.
+        Future versions of this function might fall back to other methods
+        when "fsync" on the directory fails (such as calling "sync").
         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
   SUPPORT FUNCTIONS
    EVENT PROCESSING AND EVENT LOOP INTEGRATION
     $fileno = IO::AIO::poll_fileno
         Return the *request result pipe file descriptor*. This filehandle
         must be polled for reading by some mechanism outside this module
-        (e.g. Event or select, see below or the SYNOPSIS). If the pipe
+        (e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If the
-        becomes readable you have to call "poll_cb" to check the results.
+        pipe becomes readable you have to call "poll_cb" to check the
+        results.
         See "poll_cb" for an example.
     IO::AIO::poll_cb
         Process some outstanding events on the result pipe. You have to call
         If not all requests were processed for whatever reason, the
         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:
+        IO::AIO::poll_cb with high priority (more examples can be found in
+        the SYNOPSIS section, at the top of this document):
            Event->io (fd => IO::AIO::poll_fileno,
                       poll => 'r', async => 1,
                       cb => \&IO::AIO::poll_cb);
     IO::AIO::npending
         Returns the number of requests currently in the pending state
         (executed, but not yet processed by poll_cb).
+   MISCELLANEOUS FUNCTIONS
+    IO::AIO implements some functions that might be useful, but are not
+    asynchronous.
+    IO::AIO::sendfile $ofh, $ifh, $offset, $count
+        Calls the "eio_sendfile_sync" function, which is like
+        "aio_sendfile", but is blocking (this makes most sense if you know
+        the input data is likely cached already and the output filehandle is
+        set to non-blocking operations).
+        Returns the number of bytes copied, or -1 on error.
+    IO::AIO::fadvise $fh, $offset, $len, $advice
+        Simply calls the "posix_fadvise" function (see it's manpage for
+        details). The following advice constants are avaiable:
+        "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
+        "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
+        "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
+        On systems that do not implement "posix_fadvise", this function
+        returns ENOSYS, otherwise the return value of "posix_fadvise".
   FORK BEHAVIOUR
     This module should do "the right thing" when the process using it forks:
     Before the fork, IO::AIO enters a quiescent state where no requests can
     be added in other threads and no results will be processed. After the

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.37 by root, Fri Jun 12 16:55:17 2009 UTC vs. Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.37 by root, Fri Jun 12 16:55:17 2009 UTC vs.
Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC