[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.45 by root, Thu Dec 30 07:19:31 2010 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::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
         "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
         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.45 by root, Thu Dec 30 07:19:31 2010 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.45 by root, Thu Dec 30 07:19:31 2010 UTC