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

Comparing IO-AIO/README (file contents):
Revision 1.28 by root, Sun Mar 30 06:31:49 2008 UTC vs.
Revision 1.36 by root, Sun Jun 7 18:31:18 2009 UTC

      $req->cancel; # cancel request if still in queue
      my $grp = aio_group sub { print "all stats done\n" };
      add $grp aio_stat "..." for ...;
-     # AnyEvent integration (EV, Event, Glib, Tk, urxvt, pureperl...)
+     # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
-     open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
+     use AnyEvent::AIO;
-     my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
      # EV integration
      my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
      # Event integration
     All the "aio_*" calls are more or less thin wrappers around the syscall
     with the same name (sans "aio_"). The arguments are similar or
     identical, and they all accept an additional (and optional) $callback
     argument which must be a code reference. This code reference will get
     called with the syscall return code (e.g. most syscalls return -1 on
-    error, unlike perl, which usually delivers "false") as it's sole
+    error, unlike perl, which usually delivers "false") as its sole argument
-    argument when the given syscall has been executed asynchronously.
+    after the given syscall has been executed asynchronously.
     All functions expecting a filehandle keep a copy of the filehandle
     internally until the request has finished.
     All functions return request objects of type IO::AIO::REQ that allow
     the user environment, d) use Glib::filename_from_unicode on 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 wether it is set or not.
+    handles correctly whether it is set or not.
     $prev_pri = aioreq_pri [$pri]
         Returns the priority value that would be used for the next request
         and, if $pri is given, sets the priority for the next aio request.
         Asynchronously close a file and call the callback with the result
         code.
         Unfortunately, you can't do this to perl. Perl *insists* very
         strongly on closing the file descriptor associated with the
-        filehandle itself. Here is what aio_close will try:
+        filehandle itself.
-           1. dup()licate the fd
+        Therefore, "aio_close" will not close the filehandle - instead it
-           2. asynchronously close() the duplicated fd
+        will use dup2 to overwrite the file descriptor with the write-end of
-           3. dup()licate the fd once more
+        a pipe (the pipe fd will be created on demand and will be cached).
-           4. let perl close() the filehandle
-           5. asynchronously close the duplicated fd
-        The idea is that the first close() flushes stuff to disk that
+        Or in other words: the file descriptor will be closed, but it will
-        closing an fd will flush, so when perl closes the fd, nothing much
+        not be free for reuse until the perl filehandle is closed.
-        will need to be flushed. The second async. close() will then flush
-        stuff to disk that closing the last fd to the file will flush.
-        Just FYI, SuSv3 has this to say on close:
-           All outstanding record locks owned by the process on the file
-           associated with the file descriptor shall be removed.
-           If fildes refers to a socket, close() shall cause the socket to be
-           destroyed. ... close() shall block for up to the current linger
-           interval until all data is transmitted.
-           [this actually sounds like a specification bug, but who knows]
-        And at least Linux additionally actually flushes stuff on every
-        close, even when the file itself is still open.
-        Sounds enourmously inefficient and complicated? Yes... please show
-        me how to nuke perl's fd out of existence...
     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 or to the specified $fh and
-        into the scalar given by $data and offset $dataoffset and calls the
+        $offset into the scalar given by $data and offset $dataoffset and
-        callback without the actual number of bytes read (or -1 on error,
+        calls the callback without the actual number of bytes read (or -1 on
-        just like the syscall).
+        error, just like the syscall).
+        "aio_read" will, like "sysread", shrink or grow the $data scalar to
+        offset plus the actual number of bytes read.
         If $offset is undefined, then the current file descriptor offset
         will be used (and updated), otherwise the file descriptor offset
         will not be changed by these calls.
     aio_readdir $pathname, $callback->($entries)
         Unlike the POSIX call of the same name, "aio_readdir" reads an
         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
+        The callback is passed a single argument which is either "undef" or
-        array-ref with the filenames.
+        an array-ref with the filenames.
+    aio_readdirx $pathname, $flags, $callback->($entries, $flags)
+        Quite similar to "aio_readdir", but the $flags argument allows to
+        tune behaviour and output format. In case of an error, $entries will
+        be "undef".
+        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
+            of names only (as with "aio_readdir"), otherwise it 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:
+            "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
+            "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
+            "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
+            "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
+            you need to know, you have to run stat yourself. Also, for speed
+            reasons, the $type scalars are read-only: you can not modify
+            them.
+            $inode is the inode number (which might not be exact on systems
+            with 64 bit inode numbers and 32 bit perls). On systems that do
+            not deliver the inode information, this will always be zero.
+        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
+            you need to quickly find directories, 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,
+            of which files 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
+            order will likely be fastest.
+            If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
+            specified, then the likely dirs come first, resulting in a less
+            optimal stat order.
+        IO::AIO::READDIR_FOUND_UNKNOWN
+            This flag should not be set when calling "aio_readdirx".
+            Instead, it is being set by "aio_readdirx", when any of the
+            $type's found were "IO::AIO::DT_UNKNOWN". The absense of this
+            flag therefore indicates that all $type's are known, which can
+            be used to speed up some algorithms.
     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.
-        This is a composite request that it creates the destination file
+        This is a composite request that creates the destination file with
-        with mode 0200 and copies the contents of the source file into it
+        mode 0200 and copies the contents of the source file into it using
-        using "aio_sendfile", followed by restoring atime, mtime, access
+        "aio_sendfile", followed by restoring atime, mtime, access mode and
-        mode and uid/gid, in that order.
+        uid/gid, in that order.
         If an error occurs, the partial destination file will be unlinked,
         if possible, except when setting atime, mtime, access mode and
         uid/gid, where errors are being ignored.
     aio_move $srcpath, $dstpath, $callback->($status)
         Try to move 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.
-        This is a composite request that tries to rename(2) the file first.
+        This is a composite request that tries to rename(2) the file first;
-        If rename files with "EXDEV", it copies the file with "aio_copy"
+        if rename fails with "EXDEV", it copies the file with "aio_copy"
-        and, if that is successful, unlinking the $srcpath.
+        and, if that is successful, unlinks the $srcpath.
     aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
         Scans a directory (similar to "aio_readdir") but additionally tries
         to efficiently separate the entries of directory $path into two sets
         of names, directories you can recurse into (directories), and ones
         Implementation notes.
         The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
         can.
+        If readdir returns file type information, then this is used directly
+        to find directories.
-        After reading the directory, the modification time, size etc. of the
+        Otherwise, after reading the directory, the modification time, size
-        directory before and after the readdir is checked, and if they match
+        etc. of the directory before and after the readdir is checked, and
-        (and isn't the current time), the link count will be used to decide
+        if they match (and isn't the current time), the link count will be
-        how many entries are directories (if >= 2). Otherwise, no knowledge
+        used to decide how many entries are directories (if >= 2).
-        of the number of subdirectories will be assumed.
+        Otherwise, no knowledge of the number of subdirectories will be
+        assumed.
-        Then entries will be sorted into likely directories (everything
+        Then entries will be sorted into likely directories a non-initial
-        without a non-initial dot currently) and likely non-directories
+        dot currently) and likely non-directories (see "aio_readdirx"). Then
-        (everything else). Then every entry plus an appended "/." will be
+        every entry plus an appended "/." will be "stat"'ed, likely
-        "stat"'ed, likely directories first. If that succeeds, it assumes
+        directories first, in order of their inode numbers. If that
-        that the entry is a directory or a symlink to directory (which will
+        succeeds, it assumes that the entry is a directory or a symlink to
-        be checked seperately). This is often faster than stat'ing the entry
+        directory (which will be checked seperately). This is often faster
-        itself because filesystems might detect the type of the entry
+        than stat'ing the entry itself because filesystems might detect the
-        without reading the inode data (e.g. ext2fs filetype feature).
+        type of the entry without reading the inode data (e.g. ext2fs
+        filetype feature), even on systems that cannot return the filetype
+        information on readdir.
         If the known number of directories (link count - 2) has been
         reached, the rest of the entries is assumed to be non-directories.
         This only works with certainty on POSIX (= UNIX) filesystems, which
         callback with the fdatasync result code.
         If this call isn't available because your OS lacks it or it couldn't
         be detected, it will be emulated by calling "fsync" instead.
+    aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
+        Sync the data portion of the file specified by $offset and $length
+        to disk (but NOT the metadata), by calling the Linux-specific
+        sync_file_range call. If sync_file_range is not available or it
+        returns ENOSYS, then fdatasync or fsync is being substituted.
+        $flags can be a combination of
+        "IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
+        "IO::AIO::SYNC_FILE_RANGE_WRITE" and
+        "IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
+        manpage for details.
     aio_pathsync $path, $callback->($status)
         This request tries to open, fsync and close the given path. This is
-        a composite request intended tosync directories after directory
+        a composite request intended to sync directories after directory
         operations (E.g. rename). This might not work on all operating
         systems or have any specific effect, but usually it makes sure that
         directory changes get written to disc. It works for anything that
         can be opened for read-only, not just directories.
     Their lifetime, simplified, looks like this: when they are empty, they
     will finish very quickly. If they contain only requests that are in the
     "done" state, they will also finish. Otherwise they will continue to
     exist.
-    That means after creating a group you have some time to add requests.
+    That means after creating a group you have some time to add requests
-    And in the callbacks of those requests, you can add further requests to
+    (precisely before the callback has been invoked, which is only done
-    the group. And only when all those requests have finished will the the
+    within the "poll_cb"). And in the callbacks of those requests, you can
-    group itself finish.
+    add further requests to the group. And only when all those requests have
+    finished will the the group itself finish.
     add $grp ...
     $grp->add (...)
         Add one or more requests to the group. Any type of IO::AIO::REQ can
         be added, including other groups, as long as you do not create
         does not impose any limits).
         If the feed does not queue more requests when called, it will be
         automatically removed from the group.
-        If the feed limit is 0, it will be set to 2 automatically.
+        If the feed limit is 0 when this method is called, it will be set to
+        2 automatically.
         Example:
            # stat all files in @files, but only ever use four aio requests concurrently:
     limit $grp $num
         Sets the feeder limit for the group: The feeder will be called
         whenever the group contains less than this many requests.
         Setting the limit to 0 will pause the feeding process.
+        The default value for the limit is 0, but note that setting a feeder
+        automatically bumps it up to 2.
   SUPPORT FUNCTIONS
    EVENT PROCESSING AND EVENT LOOP INTEGRATION
     $fileno = IO::AIO::poll_fileno
         Return the *request result pipe file descriptor*. This filehandle
         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 the number of events processed. Returns
+        this regularly. Returns 0 if all events could be processed, or -1 if
-        immediately when no events are outstanding. The amount of events
+        it returned earlier for whatever reason. Returns immediately when no
+        events are outstanding. The amount of events processed depends on
-        processed depends on the settings of "IO::AIO::max_poll_req" and
+        the settings of "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.
+        filehandle will still be ready when "poll_cb" returns, so normally
+        you don't have to do anything special to have it called later.
         Example: Install an Event watcher that automatically calls
         IO::AIO::poll_cb with high priority:
            Event->io (fd => IO::AIO::poll_fileno,
         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.
-    $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
+    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.
         Sets the maximum number of outstanding requests to $nreqs. If you do
         The default value is very large, so there is no practical limit on
         the number of outstanding requests.
         You can still queue as many requests as you want. Therefore,
-        "max_oustsanding" is mainly useful in simple scripts (with low
+        "max_outstanding" is mainly useful in simple scripts (with low
         values) or as a stop gap to shield against fatal memory overflow
         (with large values).
    STATISTICAL INFORMATION
     IO::AIO::nreqs
 KNOWN BUGS
     Known bugs will be fixed in the next release.
 SEE ALSO
-    Coro::AIO.
+    AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
+    more natural syntax.
 AUTHOR
      Marc Lehmann <schmorp@schmorp.de>
      http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.28 by root, Sun Mar 30 06:31:49 2008 UTC vs. Revision 1.36 by root, Sun Jun 7 18:31:18 2009 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.28 by root, Sun Mar 30 06:31:49 2008 UTC vs.
Revision 1.36 by root, Sun Jun 7 18:31:18 2009 UTC