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

Comparing IO-AIO/README (file contents):
Revision 1.43 by root, Sun Jan 10 23:44:02 2010 UTC vs.
Revision 1.46 by root, Sun Mar 27 10:26:08 2011 UTC

     IO::AIO - Asynchronous Input/Output
 SYNOPSIS
      use IO::AIO;
-     aio_open "/etc/passwd", O_RDONLY, 0, sub {
+     aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
         my $fh = shift
            or die "/etc/passwd: $!";
         ...
      };
        # register the IO::AIO callback with EV
        my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
        # queue the request to open /etc/passwd
-       aio_open "/etc/passwd", O_RDONLY, 0, sub {
+       aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
           my $fh = shift
              or die "error while opening: $!";
           # stat'ing filehandles is generally non-blocking
           my $size = -s $fh;
        aio_fdatasync $fh, $callback->($status)
        aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
        aio_pathsync $path, $callback->($status)
        aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
        aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
+       aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
+       aio_mlockall $flags, $callback->($status)
        aio_group $callback->(...)
        aio_nop $callback->()
        $prev_pri = aioreq_pri [$pri]
        aioreq_nice $pri_adjust
        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
        IO::AIO::sendfile $ofh, $ifh, $offset, $count
        IO::AIO::fadvise $fh, $offset, $len, $advice
-       IO::AIO::mlockall $flags
+       IO::AIO::madvise $scalar, $offset, $length, $advice
+       IO::AIO::mprotect $scalar, $offset, $length, $protect
+       IO::AIO::munlock $scalar, $offset = 0, $length = undef
        IO::AIO::munlockall
   AIO REQUEST FUNCTIONS
     All the "aio_*" calls are more or less thin wrappers around the syscall
     with the same name (sans "aio_"). The arguments are similar or
         will be modified by the umask in effect then the request is being
         executed, so better never change the umask.
         Example:
-           aio_open "/etc/passwd", O_RDONLY, 0, sub {
+           aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
               if ($_[0]) {
                  print "open successful, fh is $_[0]\n";
                  ...
               } else {
                  die "open failed: $!\n";
         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)
         "aio_msync", above, except for flags, which must be either 0 (which
         reads all pages and ensures they are instantiated) or
         "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading
         and writing an octet from it, which dirties the page).
+    aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
+        This is a rather advanced IO::AIO call, which works best on
+        mmap(2)ed scalars.
+        It reads in all the pages of the underlying storage into memory (if
+        any) and locks them, so they are not getting swapped/paged out or
+        removed.
+        If $length is undefined, then the scalar will be locked till the
+        end.
+        On systems that do not implement "mlock", this function returns -1
+        and sets errno to "ENOSYS".
+        Note that the corresponding "munlock" is synchronous and is
+        documented under "MISCELLANEOUS FUNCTIONS".
+        Example: open a file, mmap and mlock it - both will be undone when
+        $data gets destroyed.
+           open my $fh, "<", $path or die "$path: $!";
+           my $data;
+           IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
+           aio_mlock $data; # mlock in background
+    aio_mlockall $flags, $callback->($status)
+        Calls the "mlockall" function with the given $flags (a combination
+        of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
+        On systems that do not implement "mlockall", this function returns
+        -1 and sets errno to "ENOSYS".
+        Note that the corresponding "munlockall" is synchronous and is
+        documented under "MISCELLANEOUS FUNCTIONS".
+        Example: asynchronously lock all current and future pages into
+        memory.
+           aio_mlockall IO::AIO::MCL_FUTURE;
     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
         definite callback and the ability to cancel the whole request with
         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.
         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
+        Simply calls the "posix_fadvise" function (see its 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".
+    IO::AIO::madvise $scalar, $offset, $len, $advice
+        Simply calls the "posix_madvise" function (see its manpage for
+        details). The following advice constants are avaiable:
+        "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
+        "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
+        "IO::AIO::MADV_DONTNEED".
+        On systems that do not implement "posix_madvise", this function
+        returns ENOSYS, otherwise the return value of "posix_madvise".
+    IO::AIO::mprotect $scalar, $offset, $len, $protect
+        Simply calls the "mprotect" function on the preferably AIO::mmap'ed
+        $scalar (see its manpage for details). The following protect
+        constants are avaiable: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
+        "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
+        On systems that do not implement "mprotect", this function returns
+        ENOSYS, otherwise the return value of "mprotect".
     IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
         Memory-maps a file (or anonymous memory range) and attaches it to
         the given $scalar, which will act like a string scalar.
            my $fast_md5 = md5 $data;
     IO::AIO::munmap $scalar
         Removes a previous mmap and undefines the $scalar.
-    IO::AIO::mlockall $flags
+    IO::AIO::munlock $scalar, $offset = 0, $length = undef
-        Calls the "mlockall" function with the given $flags (a combination
+        Calls the "munlock" function, undoing the effects of a previous
-        of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL__FUTURE").
+        "aio_mlock" call (see its description for details).
-        On systems that do not implement "mlockall", this function returns
-        ENOSYS, otherwise the return value of "mlockall".
     IO::AIO::munlockall
         Calls the "munlockall" function.
         On systems that do not implement "munlockall", this function returns

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.43 by root, Sun Jan 10 23:44:02 2010 UTC vs. Revision 1.46 by root, Sun Mar 27 10:26:08 2011 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.43 by root, Sun Jan 10 23:44:02 2010 UTC vs.
Revision 1.46 by root, Sun Mar 27 10:26:08 2011 UTC