[ViewVC] Diff of: cvs/IO-AIO/AIO.pm

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.209 by root, Tue Sep 27 00:41:51 2011 UTC vs.
Revision 1.221 by root, Mon Apr 2 03:54:46 2012 UTC

 use common::sense;
 use base 'Exporter';
 BEGIN {
-   our $VERSION = '4.0';
+   our $VERSION = '4.13';
-   our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
+   our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
                      aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
                      aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_fallocate
                      aio_pathsync aio_readahead
                      aio_rename aio_link aio_move aio_copy aio_group
 documentation.
    aio_wd $pathname, $callback->($wd)
    aio_open $pathname, $flags, $mode, $callback->($fh)
    aio_close $fh, $callback->($status)
+   aio_seek  $fh,$offset,$whence, $callback->($offs)
    aio_read  $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
    aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
    aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
    aio_readahead $fh,$offset,$length, $callback->($retval)
    aio_stat  $fh_or_path, $callback->($status)
    aio_lstat $fh, $callback->($status)
    aio_statvfs $fh_or_path, $callback->($statvfs)
    aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
    aio_chown $fh_or_path, $uid, $gid, $callback->($status)
+   aio_chmod $fh_or_path, $mode, $callback->($status)
    aio_truncate $fh_or_path, $offset, $callback->($status)
-   aio_chmod $fh_or_path, $mode, $callback->($status)
    aio_unlink $pathname, $callback->($status)
    aio_mknod $pathname, $mode, $dev, $callback->($status)
    aio_link $srcpath, $dstpath, $callback->($status)
    aio_symlink $srcpath, $dstpath, $callback->($status)
    aio_readlink $pathname, $callback->($link)
    aio_rmdir $pathname, $callback->($status)
    aio_readdir $pathname, $callback->($entries)
    aio_readdirx $pathname, $flags, $callback->($entries, $flags)
       IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
       IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
+   aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
    aio_load $pathname, $data, $callback->($status)
    aio_copy $srcpath, $dstpath, $callback->($status)
    aio_move $srcpath, $dstpath, $callback->($status)
-   aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
    aio_rmtree $pathname, $callback->($status)
    aio_sync $callback->($status)
    aio_syncfs $fh, $callback->($status)
    aio_fsync $fh, $callback->($status)
    aio_fdatasync $fh, $callback->($status)
    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
-=head2 AIO REQUEST FUNCTIONS
+=head2 API NOTES
 All the C<aio_*> calls are more or less thin wrappers around the syscall
 with the same name (sans C<aio_>). The arguments are similar or identical,
 and they all accept an additional (and optional) C<$callback> argument
-which must be a code reference. This code reference will get called with
+which must be a code reference. This code reference will be called after
-the syscall return code (e.g. most syscalls return C<-1> on error, unlike
+the syscall has been executed in an asynchronous fashion. The results
-perl, which usually delivers "false") as its sole argument after the given
+of the request will be passed as arguments to the callback (and, if an
-syscall has been executed asynchronously.
+error occured, in C<$!>) - for most requests the syscall return code (e.g.
+most syscalls return C<-1> on error, unlike perl, which usually delivers
+"false").
+Some requests (such as C<aio_readdir>) pass the actual results and
+communicate failures by passing C<undef>.
 All functions expecting a filehandle keep a copy of the filehandle
 internally until the request has finished.
 All functions return request objects of type L<IO::AIO::REQ> that allow
 further manipulation of those requests while they are in-flight.
 The pathnames you pass to these routines I<should> be absolute. The
 reason for this is that at the time the request is being executed, the
-current working directory could have changed. Alternatively, you can make
+current working directory could have changed. Alternatively, you can
-sure that you never change the current working directory anywhere in
+make sure that you never change the current working directory anywhere
-the program and then use relative paths. Lastly, you can take advantage
+in the program and then use relative paths. You can also take advantage
-of IO::AIOs working directory abstraction - see the description of the
+of IO::AIOs working directory abstraction, that lets you specify paths
+relative to some previously-opened "working directory object" - see the
-C<IO::AIO::WD> class later in this document.
+description of the C<IO::AIO::WD> class later in this document.
 To encode pathnames as octets, either make sure you either: a) always pass
 in filenames you got from outside (command line, readdir etc.) without
-tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode
+tinkering, b) are in your native filesystem encoding, c) use the Encode
-your pathnames to the locale (or other) encoding in effect in the user
+module and encode your pathnames to the locale (or other) encoding in
-environment, d) use Glib::filename_from_unicode on unicode filenames or e)
+effect in the user environment, d) use Glib::filename_from_unicode on
-use something else to ensure your scalar has the correct contents.
+unicode filenames or e) use something else to ensure your scalar has the
+correct contents.
 This works, btw. independent of the internal UTF-8 bit, which IO::AIO
 handles correctly whether it is set or not.
+=head2 AIO REQUEST FUNCTIONS
 =over 4
 =item $prev_pri = aioreq_pri [$pri]
 Or in other words: the file descriptor will be closed, but it will not be
 free for reuse until the perl filehandle is closed.
 =cut
+=item aio_seek $fh, $offset, $whence, $callback->($offs)
+Seeks the filehandle to the new C<$offset>, similarly to perl's
+C<sysseek>. The C<$whence> can use the traditional values (C<0> for
+C<IO::AIO::SEEK_SET>, C<1> for C<IO::AIO::SEEK_CUR> or C<2> for
+C<IO::AIO::SEEK_END>).
+The resulting absolute offset will be passed to the callback, or C<-1> in
+case of an error.
+In theory, the C<$whence> constants could be different than the
+corresponding values from L<Fcntl>, but perl guarantees they are the same,
+so don't panic.
 =item aio_read  $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
 =item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
    my $grp = aio_group $cb;
    $maxreq = 4 if $maxreq <= 0;
-   # stat once
+   # get a wd object
    aioreq_pri $pri;
-   add $grp aio_stat $path, sub {
+   add $grp aio_wd $path, sub {
+      $_[0]
-      return $grp->result () if $_[0];
+         or return $grp->result ();
-      my $now = time;
-      my $hash1 = join ":", (stat _)[0,1,3,7,9];
-      # read the directory entries
+      my $wd = [shift, "."];
+      # stat once
       aioreq_pri $pri;
-      add $grp aio_readdirx $path, READDIR_DIRS_FIRST, sub {
+      add $grp aio_stat $wd, sub {
-         my $entries = shift
-            or return $grp->result ();
+         return $grp->result () if $_[0];
+         my $now = time;
+         my $hash1 = join ":", (stat _)[0,1,3,7,9];
-         # stat the dir another time
+         # read the directory entries
          aioreq_pri $pri;
+         add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {
+            my $entries = shift
+               or return $grp->result ();
+            # stat the dir another time
+            aioreq_pri $pri;
-         add $grp aio_stat $path, sub {
+            add $grp aio_stat $wd, sub {
-            my $hash2 = join ":", (stat _)[0,1,3,7,9];
+               my $hash2 = join ":", (stat _)[0,1,3,7,9];
-            my $ndirs;
+               my $ndirs;
-            # take the slow route if anything looks fishy
+               # take the slow route if anything looks fishy
-            if ($hash1 ne $hash2 or (stat _)[9] == $now) {
+               if ($hash1 ne $hash2 or (stat _)[9] == $now) {
-               $ndirs = -1;
+                  $ndirs = -1;
-            } else {
+               } else {
-               # if nlink == 2, we are finished
+                  # if nlink == 2, we are finished
-               # for non-posix-fs's, we rely on nlink < 2
+                  # for non-posix-fs's, we rely on nlink < 2
-               $ndirs = (stat _)[3] - 2
+                  $ndirs = (stat _)[3] - 2
-                  or return $grp->result ([], $entries);
+                     or return $grp->result ([], $entries);
-            }
+               }
-            my (@dirs, @nondirs);
+               my (@dirs, @nondirs);
-            my $statgrp = add $grp aio_group sub {
+               my $statgrp = add $grp aio_group sub {
-               $grp->result (\@dirs, \@nondirs);
+                  $grp->result (\@dirs, \@nondirs);
-            };
+               };
-            limit $statgrp $maxreq;
+               limit $statgrp $maxreq;
-            feed $statgrp sub {
+               feed $statgrp sub {
-               return unless @$entries;
+                  return unless @$entries;
-               my $entry = shift @$entries;
+                  my $entry = shift @$entries;
-               aioreq_pri $pri;
+                  aioreq_pri $pri;
+                  $wd->[1] = "$entry/.";
-               add $statgrp aio_stat "$path/$entry/.", sub {
+                  add $statgrp aio_stat $wd, sub {
-                  if ($_[0] < 0) {
+                     if ($_[0] < 0) {
-                     push @nondirs, $entry;
+                        push @nondirs, $entry;
-                  } else {
+                     } else {
-                     # need to check for real directory
+                        # need to check for real directory
-                     aioreq_pri $pri;
+                        aioreq_pri $pri;
+                        $wd->[1] = $entry;
-                     add $statgrp aio_lstat "$path/$entry", sub {
+                        add $statgrp aio_lstat $wd, sub {
-                        if (-d _) {
+                           if (-d _) {
-                           push @dirs, $entry;
+                              push @dirs, $entry;
-                           unless (--$ndirs) {
+                              unless (--$ndirs) {
-                              push @nondirs, @$entries;
+                                 push @nondirs, @$entries;
-                              feed $statgrp;
+                                 feed $statgrp;
+                              }
+                           } else {
+                              push @nondirs, $entry;
                            }
-                        } else {
-                           push @nondirs, $entry;
                         }
                      }
-                  }
+                  };
                };
             };
          };
       };
    };
 object. This object stores the canonicalised, absolute version of the
 path, and on systems that allow it, also a directory file descriptor.
 Everywhere where a pathname is accepted by IO::AIO (e.g. in C<aio_stat>
 or C<aio_unlink>), one can specify an array reference with an IO::AIO::WD
-object and a pathname instead. If the pathname is absolute, the
+object and a pathname instead (or the IO::AIO::WD object alone, which
+gets interpreted as C<[$wd, "."]>). If the pathname is absolute, the
-IO::AIO::WD objetc is ignored, otherwise the pathname is resolved relative
+IO::AIO::WD object is ignored, otherwise the pathname is resolved relative
 to that IO::AIO::WD object.
 For example, to get a wd object for F</etc> and then stat F<passwd>
 inside, you would write:
       aio_stat [$etcdir, "passwd"], sub {
          # yay
       };
    };
-This shows that creating an IO::AIO::WD object is itself a potentially
+That C<aio_wd> is a request and not a normal function shows that creating
-blocking operation, which is why it is done asynchronously.
+an IO::AIO::WD object is itself a potentially blocking operation, which is
+why it is done asynchronously.
+To stat the directory obtained with C<aio_wd> above, one could write
+either of the following three request calls:
+   aio_lstat "/etc"    , sub { ...  # pathname as normal string
+   aio_lstat [$wd, "."], sub { ...  # "." relative to $wd (i.e. $wd itself)
+   aio_lstat $wd       , sub { ...  # shorthand for the previous
 As with normal pathnames, IO::AIO keeps a copy of the working directory
 object and the pathname string, so you could write the following without
 causing any issues due to C<$path> getting reused:
 Sets a feeder/generator on this group: every group can have an attached
 generator that generates requests if idle. The idea behind this is that,
 although you could just queue as many requests as you want in a group,
 this might starve other requests for a potentially long time. For example,
-C<aio_scandir> might generate hundreds of thousands C<aio_stat> requests,
+C<aio_scandir> might generate hundreds of thousands of C<aio_stat>
-delaying any later requests for a long time.
+requests, delaying any later requests for a long time.
 To avoid this, and allow incremental generation of requests, you can
 instead a group and set a feeder on it that generates those requests. The
 feed callback will be called whenever there are few enough (see C<limit>,
 below) requests active in the group itself and is expected to queue more

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.209 by root, Tue Sep 27 00:41:51 2011 UTC vs. Revision 1.221 by root, Mon Apr 2 03:54:46 2012 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.209 by root, Tue Sep 27 00:41:51 2011 UTC vs.
Revision 1.221 by root, Mon Apr 2 03:54:46 2012 UTC