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

Comparing IO-AIO/README (file contents):
Revision 1.20 by root, Tue Oct 31 00:45:41 2006 UTC vs.
Revision 1.24 by root, Sun Aug 5 16:45:54 2007 UTC

 SYNOPSIS
      use IO::AIO;
      aio_open "/etc/passwd", O_RDONLY, 0, sub {
-        my ($fh) = @_;
+        my $fh = shift
+           or die "/etc/passwd: $!";
         ...
      };
      aio_unlink "/tmp/file", sub { };
     faster on a RAID volume or over NFS when you do a number of stat
     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
+    nonblocking operation (again, sockets, pipes etc.) is very inefficient.
-    or might not work (aio_read fails on sockets/pipes/fifos). Use an event
-    loop for that (such as the Event module): IO::AIO will naturally fit
+    Use an event loop for that (such as the Event module): IO::AIO will
-    into such an event loop itself.
+    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
     perl. In the future, this module might make use of the native aio
     not well-supported or restricted (GNU/Linux doesn't allow them on normal
     files currently, for example), and they would only support aio_read and
     aio_write, so the remaining functionality would have to be implemented
     using threads anyway.
-    Although the module will work with in the presence of other (Perl-)
+    Although the module will work in the presence of other (Perl-) threads,
-    threads, it is currently not reentrant in any way, so use appropriate
+    it is currently not reentrant in any way, so use appropriate locking
-    locking yourself, always call "poll_cb" from within the same thread, or
+    yourself, always call "poll_cb" from within the same thread, or never
-    never call "poll_cb" (or other "aio_" functions) recursively.
+    call "poll_cb" (or other "aio_" functions) recursively.
   EXAMPLE
     This is a simple example that uses the Event module and loads
     /etc/passwd asynchronously:
                   poll => 'r',
                   cb => \&IO::AIO::poll_cb);
        # queue the request to open /etc/passwd
        aio_open "/etc/passwd", O_RDONLY, 0, sub {
-          my $fh = $_[0]
+          my $fh = shift
              or die "error while opening: $!";
           # stat'ing filehandles is generally non-blocking
           my $size = -s $fh;
         They are the same as used by "sysopen".
         Likewise, $mode specifies the mode of the newly created file, if it
         didn't exist and "O_CREAT" has been given, just like perl's
         "sysopen", except that it is mandatory (i.e. use 0 if you don't
-        create new files, and 0666 or 0777 if you do).
+        create new files, and 0666 or 0777 if you do). Note that the $mode
+        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 {
               if ($_[0]) {
         This is supposed to be a bug in the API, so that might change. It's
         therefore best to avoid this function.
     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"
+        Reads or writes $length bytes from the specified $fh and $offset
-        into the scalar given by "data" and offset "dataoffset" and calls
+        into the scalar given by $data and offset $dataoffset and calls the
-        the callback without the actual number of bytes read (or -1 on
+        callback without the actual number of bytes read (or -1 on error,
-        error, just like the syscall).
+        just like the syscall).
+        If $offset is undefined, then the current file offset will be used
+        (and updated), otherwise the file offset will not be changed by
+        these calls.
+        If $length is undefined in "aio_write", use the remaining length of
+        $data.
+        If $dataoffset is less than zero, it will be counted from the end of
+        $data.
         The $data scalar *MUST NOT* be modified in any way while the request
-        is outstanding. Modifying it can result in segfaults or WW3 (if the
+        is outstanding. Modifying it can result in segfaults or World War
-        necessary/optional hardware is installed).
+        III (if the necessary/optional hardware is installed).
         Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
         offset 0 within the scalar:
            aio_read $fh, 7, 15, $buffer, 0, sub {
            aio_stat "/etc/passwd", sub {
               $_[0] and die "stat failed: $!";
               print "size is ", -s _, "\n";
            };
+    aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
+        Works like perl's "utime" function (including the special case of
+        $atime and $mtime being undef). Fractional times are supported if
+        the underlying syscalls support them.
+        When called with a pathname, uses utimes(2) if available, otherwise
+        utime(2). If called on a file descriptor, uses futimes(2) if
+        available, otherwise returns ENOSYS, so this is not portable.
+        Examples:
+           # set atime and mtime to current time (basically touch(1)):
+           aio_utime "path", undef, undef;
+           # set atime to current time and mtime to beginning of the epoch:
+           aio_utime "path", time, undef; # undef==0
+    aio_chown $fh_or_path, $uid, $gid, $callback->($status)
+        Works like perl's "chown" function, except that "undef" for either
+        $uid or $gid is being interpreted as "do not change" (but -1 can
+        also be used).
+        Examples:
+           # same as "chown root path" in the shell:
+           aio_chown "path", 0, -1;
+           # same as above:
+           aio_chown "path", 0, undef;
+    aio_truncate $fh_or_path, $offset, $callback->($status)
+        Works like truncate(2) or ftruncate(2).
+    aio_chmod $fh_or_path, $mode, $callback->($status)
+        Works like perl's "chmod" function.
     aio_unlink $pathname, $callback->($status)
         Asynchronously unlink (delete) a file and call the callback with the
         result code.
     aio_mknod $path, $mode, $dev, $callback->($status)
     aio_rename $srcpath, $dstpath, $callback->($status)
         Asynchronously rename the object at $srcpath to $dstpath, just as
         rename(2) and call the callback with the result code.
+    aio_mkdir $pathname, $mode, $callback->($status)
+        Asynchronously mkdir (create) a directory and call the callback with
+        the result code. $mode will be modified by the umask at the time the
+        request is executed, so do not change your umask.
     aio_rmdir $pathname, $callback->($status)
         Asynchronously rmdir (delete) a directory and call the callback with
         the result code.
     aio_readdir $pathname, $callback->($entries)
         entire directory (i.e. opendir + readdir + closedir). The entries
         will not be sorted, and will NOT include the "." and ".." entries.
         The callback a single argument which is either "undef" or an
         array-ref with the filenames.
+    aio_load $path, $data, $callback->($status)
+        This is a composite request that tries to fully load the given file
+        into memory. Status is the same as with aio_read.
     aio_copy $srcpath, $dstpath, $callback->($status)
         Try to copy the *file* (directories not supported as either source
         or destination) from $srcpath to $dstpath and call the callback with
         the 0 (error) or -1 ok.
         It will also likely work on non-POSIX filesystems with reduced
         efficiency as those tend to return 0 or 1 as link counts, which
         disables the directory counting heuristic.
+    aio_rmtree $path, $callback->($status)
+        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_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)
            Event->io (fd => IO::AIO::poll_fileno,
                       poll => 'r', nice => 1,
                       cb => &IO::AIO::poll_cb);
     IO::AIO::poll_wait
+        If there are any outstanding requests and none of them in the result
-        Wait till the result filehandle becomes ready for reading (simply
+        phase, wait till the result filehandle becomes ready for reading
-        does a "select" on the filehandle. This is useful if you want to
+        (simply does a "select" on the filehandle. This is useful if you
-        synchronously wait for some requests to finish).
+        want to synchronously wait for some requests to finish).
         See "nreqs" for an example.
     IO::AIO::poll
         Waits until some requests have been handled.
+        Returns the number of requests processed, but is otherwise strictly
-        Strictly equivalent to:
+        equivalent to:
            IO::AIO::poll_wait, IO::AIO::poll_cb
-              if IO::AIO::nreqs;
     IO::AIO::flush
         Wait till all outstanding AIO requests have been handled.
         Strictly equivalent to:

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.20 by root, Tue Oct 31 00:45:41 2006 UTC vs. Revision 1.24 by root, Sun Aug 5 16:45:54 2007 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.20 by root, Tue Oct 31 00:45:41 2006 UTC vs.
Revision 1.24 by root, Sun Aug 5 16:45:54 2007 UTC