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

Comparing IO-AIO/README (file contents):
Revision 1.44 by root, Mon Nov 1 22:03:43 2010 UTC vs.
Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC

        IO::AIO::max_poll_reqs $nreqs
        IO::AIO::max_poll_time $seconds
        IO::AIO::min_parallel $nthreads
        IO::AIO::max_parallel $nthreads
        IO::AIO::max_idle $nthreads
+       IO::AIO::idle_timeout $seconds
        IO::AIO::max_outstanding $maxreqs
        IO::AIO::nreqs
        IO::AIO::nready
        IO::AIO::npending
               } else {
                  die "open failed: $!\n";
               }
            };
+        In addition to all the common open modes/flags ("O_RDONLY",
+        "O_WRONLY", "O_RDWR", "O_CREAT", "O_TRUNC", "O_EXCL" and
+        "O_APPEND"), the following POSIX and non-POSIX constants are
+        available (missing ones on your system are, as usual, 0):
+        "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
+        "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
+        "O_DSYNC", "O_RSYNC", "O_SYNC" and "O_TTY_INIT".
     aio_close $fh, $callback->($status)
         Asynchronously close a file and call the callback with the result
         code.
         Unfortunately, you can't do this to perl. Perl *insists* very
         reading at byte offset $in_offset, and starts writing at the current
         file offset of $out_fh. Because of that, it is not safe to issue
         more than one "aio_sendfile" per $out_fh, as they will interfere
         with each other.
+        Please note that "aio_sendfile" can read more bytes from $in_fh than
+        are written, and there is no way to find out how many bytes have
+        been read from "aio_sendfile" alone, as "aio_sendfile" only provides
+        the number of bytes written to $out_fh. Only if the result value
+        equals $length one can assume that $length bytes have been read.
+        Unlike with other "aio_" functions, it makes a lot of sense to use
+        "aio_sendfile" on non-blocking sockets, as long as one end
+        (typically the $in_fh) is a file - the file I/O will then be
+        asynchronous, while the socket I/O will be non-blocking. Note,
+        however, that you can run into a trap where "aio_sendfile" reads
+        some data with readahead, then fails to write all data, and when the
+        socket is ready the next time, the data in the cache is already
+        lost, forcing "aio_sendfile" to again hit the disk. Explicit
+        "aio_read" + "aio_write" let's you control resource usage much
+        better.
         This call tries to make use of a native "sendfile" syscall to
         provide zero-copy operation. For this to work, $out_fh should refer
         to a socket, and $in_fh should refer to an mmap'able file.
         If a native sendfile cannot be found or it fails with "ENOSYS",
         "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK",
         it will be emulated, so you can call "aio_sendfile" on any type of
         filehandle regardless of the limitations of the operating system.
-        Please note, however, that "aio_sendfile" can read more bytes from
-        $in_fh than are written, and there is no way to find out how many
-        bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
-        only provides the number of bytes written to $out_fh. Only if the
-        result value equals $length one can assume that $length bytes have
-        been read.
     aio_readahead $fh,$offset,$length, $callback->($retval)
         "aio_readahead" populates the page cache with data from a file so
         that subsequent reads from that file will not block on disk I/O. The
         $offset argument specifies the starting point from which data is to
         Currently, the stats are always 64-bit-stats, i.e. instead of
         returning an error when stat'ing a large file, the results will be
         silently truncated unless perl itself is compiled with large file
         support.
+        To help interpret the mode and dev/rdev stat values, IO::AIO offers
+        the following constants and functions (if not implemented, the
+        constants will be 0 and the functions will either "croak" or fall
+        back on traditional behaviour).
+        "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
+        "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
+        "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
         Example: Print the length of /etc/passwd:
            aio_stat "/etc/passwd", sub {
               $_[0] and die "stat failed: $!";
         The only (POSIX-) portable way of calling this function is:
            aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
+        See "aio_stat" for info about some potentially helpful extra
+        constants and functions.
     aio_link $srcpath, $dstpath, $callback->($status)
         Asynchronously create a new link to the existing object at $srcpath
         at the path $dstpath and call the callback with the result code.
     aio_symlink $srcpath, $dstpath, $callback->($status)
         The flags are a combination of the following constants, ORed
         together (the flags will also be passed to the callback, possibly
         modified):
         IO::AIO::READDIR_DENTS
-            When this flag is off, then the callback gets an arrayref with
+            When this flag is off, then the callback gets an arrayref
-            of names only (as with "aio_readdir"), otherwise it gets an
+            consisting of names only (as with "aio_readdir"), otherwise it
-            arrayref with "[$name, $type, $inode]" arrayrefs, each
+            gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
             describing a single directory entry in more detail.
             $name is the name of the entry.
             $type is one of the "IO::AIO::DT_xxx" constants:
             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
+            order where likely directories come first, in optimal stat
-            you need to quickly find directories, or you want to find all
+            order. This is useful when you need to quickly find directories,
-            directories while avoiding to stat() each entry.
+            or you want to find all directories while avoiding to stat()
+            each entry.
             If the system returns type information in readdir, then this is
             used to find directories directly. Otherwise, likely directories
-            are files beginning with ".", or otherwise files with no dots,
+            are names beginning with ".", or otherwise names with no dots,
-            of which files with short names are tried first.
+            of which names with short names are tried first.
         IO::AIO::READDIR_STAT_ORDER
             When this flag is set, then the names will be returned in an
             order suitable for stat()'ing each one. That is, when you plan
             to stat() all files in the given directory, then the returned
         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 0 if all events could be processed, or -1 if
+        this regularly. Returns 0 if all events could be processed (or there
-        it returned earlier for whatever reason. Returns immediately when no
+        were no events to process), or -1 if it returned earlier for
-        events are outstanding. The amount of events processed depends on
+        whatever reason. Returns immediately when no events are outstanding.
-        the settings of "IO::AIO::max_poll_req" and
+        The amount of events processed depends on the settings of
-        "IO::AIO::max_poll_time".
+        "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, so normally
         you don't have to do anything special to have it called later.
+        Apart from calling "IO::AIO::poll_cb" when the event filehandle
+        becomes ready, it can be beneficial to call this function from loops
+        which submit a lot of requests, to make sure the results get
+        processed when they become available and not just when the loop is
+        finished and the event loop takes over again. This function returns
+        very fast when there are no outstanding requests.
         Example: Install an Event watcher that automatically calls
         IO::AIO::poll_cb with high priority (more examples can be found in
         the SYNOPSIS section, at the top of this document):
         Under normal circumstances you don't need to call this function.
     IO::AIO::max_idle $nthreads
         Limit the number of threads (default: 4) that are allowed to idle
-        (i.e., threads that did not get a request to process within 10
+        (i.e., threads that did not get a request to process within the idle
-        seconds). That means if a thread becomes idle while $nthreads other
+        timeout (default: 10 seconds). That means if a thread becomes idle
-        threads are also idle, it will free its resources and exit.
+        while $nthreads other threads are also idle, it will free its
+        resources and exit.
         This is useful when you allow a large number of threads (e.g. 100 or
         1000) to allow for extremely high load situations, but want to free
         resources under normal circumstances (1000 threads can easily
         consume 30MB of RAM).
         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.
+    IO::AIO::idle_timeout $seconds
+        Sets the minimum idle timeout (default 10) after which worker
+        threads are allowed to exit. SEe "IO::AIO::max_idle".
     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.

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.44 by root, Mon Nov 1 22:03:43 2010 UTC vs. Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.44 by root, Mon Nov 1 22:03:43 2010 UTC vs.
Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC