--- IO-AIO/AIO.pm 2005/07/10 17:07:44 1.1 +++ IO-AIO/AIO.pm 2005/08/17 05:26:20 1.32 @@ -6,137 +6,127 @@ use IO::AIO; + aio_open "/etc/passwd", O_RDONLY, 0, sub { + my ($fh) = @_; + ... + }; + + aio_unlink "/tmp/file", sub { }; + + aio_read $fh, 30000, 1024, $buffer, 0, sub { + $_[0] > 0 or die "read error: $!"; + }; + + # Event + Event->io (fd => IO::AIO::poll_fileno, + poll => 'r', + cb => \&IO::AIO::poll_cb); + + # Glib/Gtk2 + add_watch Glib::IO IO::AIO::poll_fileno, + 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. Currently, it falls back to Linux::AIO if that -module is available, or uses pthreads to emulato aio functionality. +operating system supports. -Currently, in this module a number of threads are started that execute -your read/writes and signal their completion. You don't need thread -support in your libc or perl, and the threads created by this module will -not be visible to the pthreads library. +Currently, a number of threads are started that execute your read/writes +and signal their completion. You don't need thread support in your libc or +perl, and the threads created by this module will not be visible to the +pthreads library. In the future, this module might make use of the native +aio functions available on many operating systems. However, they are often +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 -not reentrant, so use appropriate locking yourself. - -=head2 API NOTES - -All the C calls are more or less thin wrappers around the syscall -with the same name (sans C). The arguments are similar or identical, -and they all accept an additional C<$callback> argument which must be -a code reference. This code reference will get called with the syscall -return code (e.g. most syscalls return C<-1> on error, unlike perl, which -usually delivers "false") as it's sole argument when the given syscall has -been executed asynchronously. - -All functions that expect a filehandle will also accept a file descriptor. - -The filenames you pass to these routines I be absolute. The reason -is that at the time the request is being executed, the current working -directory could have changed. Alternatively, you can make sure that you -never change the current working directory. - -=over 4 +currently not reentrant, so use appropriate locking yourself, always call +C from within the same thread, or never call C (or other +C functions) recursively. =cut package IO::AIO; +no warnings; + use base 'Exporter'; +use Fcntl (); + BEGIN { - $VERSION = 0.1; + $VERSION = 1.3; + @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink - aio_fsync aio_fdatasync aio_readahead); - @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs); + 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; } -=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 -(the number of outstanding operations, however, is unlimited). - -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). - -Under normal circumstances you don't need to call this function, as this -module automatically starts a single async thread. - -=item IO::AIO::max_parallel $nthreads - -Sets the maximum number of AIO threads to C<$nthreads>. If more than -the specified number of threads are currently running, kill them. This -function blocks until the limit is reached. +=head1 FUNCTIONS -This module automatically runs C at program end, to ensure -that all threads are killed and that there are no outstanding requests. +=head2 AIO FUNCTIONS -Under normal circumstances you don't need to call this function. - -=item $fileno = IO::AIO::poll_fileno - -Return the I. This filehandle must be -polled for reading by some mechanism outside this module (e.g. Event -or select, see below). If the pipe becomes readable you have to call -C to check the results. - -See C 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.: - - 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 -for some requests to finish). - -See C for an example. - -=item IO::AIO::nreqs - -Returns the number of requests currently outstanding. - -Example: wait till there are no outstanding requests anymore: +All the C calls are more or less thin wrappers around the syscall +with the same name (sans C). 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 +the syscall return code (e.g. most syscalls return C<-1> on error, unlike +perl, which usually delivers "false") as it's sole argument when the given +syscall has been executed asynchronously. + +All functions expecting a filehandle keep a copy of the filehandle +internally until the request has finished. + +The pathnames you pass to these routines I be absolute and +encoded in byte form. The reason for the former is that at the time the +request is being executed, the current working directory could have +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. - IO::AIO::poll_wait, IO::AIO::poll_cb - while IO::AIO::nreqs; +=over 4 =item aio_open $pathname, $flags, $mode, $callback -Asynchronously open or create a file and call the callback with the -filedescriptor (NOT a perl filehandle, sorry for that, but watch out, this -might change in the future). +Asynchronously open or create a file and call the callback with a newly +created filehandle for the file. The pathname passed to C must be absolute. See API NOTES, above, for an explanation. -The C<$mode> argument is a bitmask. See the C module for a -list. They are the same as used in C. +The C<$flags> argument is a bitmask. See the C module for a +list. They are the same as used by C. + +Likewise, C<$mode> specifies the mode of the newly created file, if it +didn't exist and C has been given, just like perl's C, +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] >= 0) { - open my $fh, "<&$_[0]"; # create a copy for perl - aio_close $_[0], sub { }; # close the aio handle - print "open successful, fh is $fh\n"; + if ($_[0]) { + print "open successful, fh is $_[0]\n"; ... } else { die "open failed: $!\n"; @@ -145,7 +135,14 @@ =item aio_close $fh, $callback -Asynchronously close a file and call the callback with the result code. +Asynchronously close a file and call the callback with the result +code. I although accepted, you should not pass in a perl +filehandle here, as perl will likely close the file descriptor another +time when the filehandle is destroyed. Normally, you can safely call perls +C 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 @@ -156,29 +153,32 @@ callback without the actual number of bytes read (or -1 on error, just like the syscall). -Example: Read 15 bytes at offset 7 into scalar C<$buffer>, strating at +The C<$data> scalar I 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 <$buffer>\n"; + $_[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 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 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 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 @@ -206,6 +206,11 @@ 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 @@ -216,8 +221,131 @@ 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 instead. + +=back + +=head2 SUPPORT FUNCTIONS + +=over 4 + +=item $fileno = IO::AIO::poll_fileno + +Return the I. This filehandle must be +polled for reading by some mechanism outside this module (e.g. Event or +select, see below or the SYNOPSIS). If the pipe becomes readable you have +to call C to check the results. + +See C 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. + +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 +C