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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.26 by root, Sun Aug 7 03:34:07 2005 UTC vs.
Revision 1.39 by root, Sun Aug 28 11:05:50 2005 UTC

 use base 'Exporter';
 use Fcntl ();
 BEGIN {
-   $VERSION = 1.1;
+   $VERSION = 1.6;
-   @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
+   @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
+                aio_lstat aio_unlink aio_rmdir aio_readdir aio_symlink
                 aio_fsync aio_fdatasync aio_readahead);
-   @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
+   @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel
+                   max_outstanding nreqs);
    require XSLoader;
    XSLoader::load IO::AIO, $VERSION;
 }
 syscall has been executed asynchronously.
 All functions expecting a filehandle keep a copy of the filehandle
 internally until the request has finished.
-The filenames you pass to these routines I<must> be absolute. The reason
+The pathnames you pass to these routines I<must> be absolute and
-for this is that at the time the request is being executed, the current
+encoded in byte form. The reason for the former is that at the time the
-working directory could have changed. Alternatively, you can make sure
+request is being executed, the current working directory could have
-that you never change the current working directory.
+changed. Alternatively, you can make sure that you never change the
+current working directory.
+To encode pathnames to byte form, either make sure you either: a)
+always pass in filenames you got from outside (command line, readdir
+etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and encode
+your pathnames to the locale (or other) encoding in effect in the user
+environment, d) use Glib::filename_from_unicode on unicode filenames or e)
+use something else.
 =over 4
 =item aio_open $pathname, $flags, $mode, $callback
 Reads or writes C<length> bytes from the specified C<fh> and C<offset>
 into the scalar given by C<data> and offset C<dataoffset> and calls the
 callback without the actual number of bytes read (or -1 on error, just
 like the syscall).
+The C<$data> scalar I<MUST NOT> be modified in any way while the request
+is outstanding. Modifying it can result in segfaults or WW3 (if the
+necessary/optional hardware is installed).
 Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at
 offset C<0> within the scalar:
    aio_read $fh, 7, 15, $buffer, 0, sub {
       $_[0] > 0 or die "read error: $!";
       print "read $_[0] bytes: <$buffer>\n";
    };
+=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback
+Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
+reading at byte offset C<$in_offset>, and starts writing at the current
+file offset of C<$out_fh>. Because of that, it is not safe to issue more
+than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
+other.
+This call tries to make use of a native C<sendfile> syscall to provide
+zero-copy operation. For this to work, C<$out_fh> should refer to a
+socket, and C<$in_fh> should refer to mmap'able file.
+If the native sendfile call fails or is not implemented, it will be
+emulated, so you can call C<aio_sendfile> on any type of filehandle
+regardless of the limitations of the operating system.
+Please note, however, that C<aio_sendfile> can read more bytes from
+C<$in_fh> than are written, and there is no way to find out how many
+bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
+provides the number of bytes written to C<$out_fh>. Only if the result
+value equals C<$length> one can assume that C<$length> bytes have been
+read.
 =item aio_readahead $fh,$offset,$length, $callback
 C<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 C<$offset>
 =item aio_unlink $pathname, $callback
 Asynchronously unlink (delete) a file and call the callback with the
 result code.
+=item aio_rmdir $pathname, $callback
+Asynchronously rmdir (delete) a directory and call the callback with the
+result code.
+=item aio_readdir $pathname $callback
+Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
+directory (i.e. opendir + readdir + closedir). The entries will not be
+sorted, and will B<NOT> include the C<.> and C<..> entries.
+The callback a single argument which is either C<undef> or an array-ref
+with the filenames.
 =item aio_fsync $fh, $callback
 Asynchronously call fsync on the given filehandle and call the callback
 with the fsync result code.
    IO::AIO::poll_wait, IO::AIO::poll_cb
       if IO::AIO::nreqs;
 =item IO::AIO::min_parallel $nthreads
-Set the minimum number of AIO threads to C<$nthreads>. The default is
+Set the minimum number of AIO threads to C<$nthreads>. The current default
-C<1>, which means a single asynchronous operation can be done at one time
+is C<4>, which means four asynchronous operations can be done at one time
 (the number of outstanding operations, however, is unlimited).
+IO::AIO starts threads only on demand, when an AIO request is queued and
+no free thread exists.
 It is recommended to keep the number of threads low, as some Linux
 kernel versions will scale negatively with the number of threads (higher
 parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
 threads should be fine.
-Under normal circumstances you don't need to call this function, as this
+Under most circumstances you don't need to call this function, as the
-module automatically starts some threads (the exact number might change,
+module selects a default that is suitable for low to moderate load.
-and is currently 4).
 =item IO::AIO::max_parallel $nthreads
-Sets the maximum number of AIO threads to C<$nthreads>. If more than
+Sets the maximum number of AIO threads to C<$nthreads>. If more than the
-the specified number of threads are currently running, kill them. This
+specified number of threads are currently running, this function kills
-function blocks until the limit is reached.
+them. This function blocks until the limit is reached.
+While C<$nthreads> are zero, aio requests get queued but not executed
+until the number of threads has been increased again.
 This module automatically runs C<max_parallel 0> at program end, to ensure
 that all threads are killed and that there are no outstanding requests.
 Under normal circumstances you don't need to call this function.
 Sets the maximum number of outstanding requests to C<$nreqs>. If you
 try to queue up more than this number of requests, the caller will block until
 some requests have been handled.
 The default is very large, so normally there is no practical limit. If you
-queue up many requests in a loop it it often improves speed if you set
+queue up many requests in a loop it often improves speed if you set
 this to a relatively low number, such as C<100>.
 Under normal circumstances you don't need to call this function.
 =back
    # try to generate nice filehandles
    my $sym = "IO::AIO::fd#$_[0]";
    local *$sym;
-   open *$sym, "+<&$_[0]"      # usually under any unix
+   open *$sym, "+<&=$_[0]"      # usually works under any unix
-      or open *$sym, "<&$_[0]" # cygwin needs this
+      or open *$sym, "<&=$_[0]" # cygwin needs this
-      or open *$sym, ">&$_[0]" # cygwin needs this
+      or open *$sym, ">&=$_[0]" # or this
       or return undef;
    *$sym
 }
    max_parallel 0;
 }
 1;
+=head2 FORK BEHAVIOUR
+Before the fork, IO::AIO enters a quiescent state where no requests
+can be added in other threads and no results will be processed. After
+the fork the parent simply leaves the quiescent state and continues
+request/result processing, while the child clears the request/result
+queue (so the requests started before the fork will only be handled in
+the parent). Threats will be started on demand until the limit ste in the
+parent process has been reached again.
 =head1 SEE ALSO
 L<Coro>, L<Linux::AIO>.
 =head1 AUTHOR

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.26 by root, Sun Aug 7 03:34:07 2005 UTC vs. Revision 1.39 by root, Sun Aug 28 11:05:50 2005 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.26 by root, Sun Aug 7 03:34:07 2005 UTC vs.
Revision 1.39 by root, Sun Aug 28 11:05:50 2005 UTC