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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.9 by root, Sun Jul 10 22:20:55 2005 UTC vs.
Revision 1.33 by root, Wed Aug 17 06:12:10 2005 UTC

             poll => 'r',
             cb => \&IO::AIO::poll_cb);
  # Glib/Gtk2
  add_watch Glib::IO IO::AIO::poll_fileno,
-           \&IO::AIO::poll_cb;
+           in => sub { IO::AIO::poll_cb; 1 };
  # Tk
  Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
                            readable => \&IO::AIO::poll_cb);
+ # Danga::Socket
+ Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
+                             \&IO::AIO::poll_cb);
 =head1 DESCRIPTION
 This module implements asynchronous I/O using whatever means your
 operating system supports.
 not well-supported (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 threads, it is
-currently not reentrant, so use appropriate locking yourself.
+currently not reentrant, so use appropriate locking yourself, always call
+C<poll_cb> from within the same thread, or never call C<poll_cb> (or other
+C<aio_> functions) recursively.
 =cut
 package IO::AIO;
+no warnings;
 use base 'Exporter';
 use Fcntl ();
 BEGIN {
-   $VERSION = 0.2;
+   $VERSION = 1.4;
    @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
-                aio_fsync aio_fdatasync aio_readahead);
+                aio_rmdir aio_symlink aio_fsync aio_fdatasync aio_readahead);
    @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
    require XSLoader;
    XSLoader::load IO::AIO, $VERSION;
 }
 =head2 AIO FUNCTIONS
 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 C<$callback> argument which must be
+and they all accept an additional (and optional) C<$callback> argument
-a code reference. This code reference will get called with the syscall
+which must be a code reference. This code reference will get called with
-return code (e.g. most syscalls return C<-1> on error, unlike perl, which
+the syscall return code (e.g. most syscalls return C<-1> on error, unlike
-usually delivers "false") as it's sole argument when the given syscall has
+perl, which usually delivers "false") as it's sole argument when the given
-been executed asynchronously.
+syscall has been executed asynchronously.
-All functions that expect a filehandle will also accept a file descriptor.
+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
-is that at the time the request is being executed, the current working
+encoded in byte form. The reason for the former is that at the time the
-directory could have changed. Alternatively, you can make sure that you
+request is being executed, the current working directory could have
+changed. Alternatively, you can make sure that you never change the
-never change the current working directory.
+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
 created filehandle for the file.
 The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
 for an explanation.
-The C<$mode> argument is a bitmask. See the C<Fcntl> module for a
+The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
-list. They are the same as used in C<sysopen>.
+list. They are the same as used by C<sysopen>.
+Likewise, C<$mode> specifies the mode of the newly created file, if it
+didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
+except that it is mandatory (i.e. use C<0> if you don't create new files,
+and C<0666> or C<0777> if you do).
 Example:
    aio_open "/etc/passwd", O_RDONLY, 0, sub {
       if ($_[0]) {
 =item aio_close $fh, $callback
 Asynchronously close a file and call the callback with the result
 code. I<WARNING:> although accepted, you should not pass in a perl
-filehandle here, as perl will likely close the file descriptor itself when
+filehandle here, as perl will likely close the file descriptor another
-the filehandle is destroyed. Normally, you can safely call perls C<close>
+time when the filehandle is destroyed. Normally, you can safely call perls
-or just let filehandles go out of scope.
+C<close> or just let filehandles go out of scope.
+This is supposed to be a bug in the API, so that might change. It's
+therefore best to avoid this function.
 =item aio_read  $fh,$offset,$length, $data,$dataoffset,$callback
 =item aio_write $fh,$offset,$length, $data,$dataoffset,$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>, strating at
+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_readahead $fh,$offset,$length, $callback
-Asynchronously reads the specified byte range into the page cache, using
-the C<readahead> syscall. If that syscall doesn't exist the status will be
-C<-1> and C<$!> is set to ENOSYS.
-readahead() populates the page cache with data from a file so that
+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>
 argument specifies the starting point from which data is to be read and
 C<$length> specifies the number of bytes to be read. I/O is performed in
 whole pages, so that offset is effectively rounded down to a page boundary
 and bytes are read up to the next page boundary greater than or equal to
-(off-set+length). aio_readahead() does not read beyond the end of the
+(off-set+length). C<aio_readahead> does not read beyond the end of the
 file. The current file offset of the file is left unchanged.
+If that syscall doesn't exist (likely if your OS isn't Linux) it will be
+emulated by simply reading the data, which would have a similar effect.
 =item aio_stat  $fh_or_path, $callback
 =item aio_lstat $fh, $callback
 =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_fsync $fh, $callback
 Asynchronously call fsync on the given filehandle and call the callback
 with the fsync result code.
 =item aio_fdatasync $fh, $callback
 Asynchronously call fdatasync on the given filehandle and call the
 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 C<fsync> instead.
 =back
 =head2 SUPPORT FUNCTIONS
 =over 4
 =item $fileno = IO::AIO::poll_fileno
-Return the I<request result pipe filehandle>. This filehandle must be
+Return the I<request result pipe file descriptor>. This filehandle must be
-polled for reading by some mechanism outside this module (e.g. Event
+polled for reading by some mechanism outside this module (e.g. Event or
-or select, see below). If the pipe becomes readable you have to call
+select, see below or the SYNOPSIS). If the pipe becomes readable you have
-C<poll_cb> to check the results.
+to call C<poll_cb> to check the results.
 See C<poll_cb> for an example.
 =item IO::AIO::poll_cb
 Process all outstanding events on the result pipe. You have to call this
 regularly. Returns the number of events processed. Returns immediately
 when no events are outstanding.
-You can use Event to multiplex, e.g.:
+Example: Install an Event watcher that automatically calls
+IO::AIO::poll_cb with high priority:
    Event->io (fd => IO::AIO::poll_fileno,
               poll => 'r', async => 1,
               cb => \&IO::AIO::poll_cb);
 =item IO::AIO::poll_wait
 Wait till the result filehandle becomes ready for reading (simply does a
-select on the filehandle. This is useful if you want to synchronously wait
+C<select> on the filehandle. This is useful if you want to synchronously wait
 for some requests to finish).
 See C<nreqs> for an example.
 =item IO::AIO::nreqs
-Returns the number of requests currently outstanding.
+Returns the number of requests currently outstanding (i.e. for which their
+callback has not been invoked yet).
 Example: wait till there are no outstanding requests anymore:
    IO::AIO::poll_wait, IO::AIO::poll_cb
       while IO::AIO::nreqs;
+=item IO::AIO::flush
+Wait till all outstanding AIO requests have been handled.
+Strictly equivalent to:
+   IO::AIO::poll_wait, IO::AIO::poll_cb
+      while IO::AIO::nreqs;
+=item IO::AIO::poll
+Waits until some requests have been handled.
+Strictly equivalent to:
+   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
 C<1>, which means a single asynchronous operation can be done at one time
 # support function to convert a fd into a perl filehandle
 sub _fd2fh {
    return undef if $_[0] < 0;
-   # try to be perl5.6-compatible
+   # try to generate nice filehandles
-   local *AIO_FH;
+   my $sym = "IO::AIO::fd#$_[0]";
-   open AIO_FH, "+<&=$_[0]"
+   local *$sym;
+   open *$sym, "+<&=$_[0]"      # usually works under any unix
+      or open *$sym, "<&=$_[0]" # cygwin needs this
+      or open *$sym, ">&=$_[0]" # or this
       or return undef;
-   *AIO_FH
+   *$sym
 }
 min_parallel 4;
 END {
    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 and starts the
+same number of threads as were in use by the parent.
 =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.9 by root, Sun Jul 10 22:20:55 2005 UTC vs. Revision 1.33 by root, Wed Aug 17 06:12:10 2005 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.9 by root, Sun Jul 10 22:20:55 2005 UTC vs.
Revision 1.33 by root, Wed Aug 17 06:12:10 2005 UTC