--- Linux-AIO/AIO.pm 2002/05/18 21:48:36 1.12 +++ Linux-AIO/AIO.pm 2005/06/29 15:28:14 1.24 @@ -8,11 +8,22 @@ =head1 DESCRIPTION -This module implements asynchroneous i/o using the means available to -linux - clone. It does not hook into the POSIX aio_* functions because -linux does not yet support these in the kernel. Instead, a number of -threads are started that execute your read/writes and signal their -completion. +This module implements asynchronous i/o using the means available to linux +- clone. It does not hook into the POSIX aio_* functions because linux +does not yet support these in the kernel (and even if, it would only allow +aio_read and write, not open and stat). + +Instead, in this module a number of (non-posix) 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. + +NOTICE: the threads created by this module will automatically be killed +when the thread calling min_parallel exits. Make sure you only ever call +min_parallel from the same thread that loaded this module. + +Although the module will work with threads, it is not reentrant, so use +appropriate locking yourself. =over 4 @@ -23,73 +34,101 @@ use base 'Exporter'; BEGIN { - $VERSION = 0.111; + $VERSION = 1.5; - @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat); + @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink); @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs); require XSLoader; XSLoader::load Linux::AIO, $VERSION; } -=item Linux::AIO::min_parallel($nthreads) +=item Linux::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). + +=item Linux::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. -Set the minimum number of AIO threads to $nthreads. You I to call -this function with a positive number at leats once, otherwise no threads -will be started and you aio-operations will seem to hang. +This module automatically runs C at program end, to ensure +that all threads are killed and that there are no outstanding requests. =item $fileno = Linux::AIO::poll_fileno -Return the request result pipe filehandle. This filehandle must be polled -for reading. If the pipe becomes readable you have to call C. +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. =item Linux::AIO::poll_cb Process all outstanding events on the result pipe. You have to call this -regularly. Returns the number of events processed. +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 => Linux::AIO::poll_fileno, - poll => 'r', async => 1, - cb => \&Linux::AIO::poll_cb ); - + Event->io (fd => Linux::AIO::poll_fileno, + poll => 'r', async => 1, + cb => \&Linux::AIO::poll_cb ); + +=item Linux::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). =item Linux::AIO::nreqs Returns the number of requests currently outstanding. -=item aio_open($pathname, $flags, $mode, $callback) +=item aio_open $pathname, $flags, $mode, $callback Asynchronously open or create a file and call the callback with the -filedescriptor. +filedescriptor (NOT a perl filehandle, sorry for that, but watch out, this +might change in the future). -=item aio_close($fh, $callback) +=item aio_close $fh, $callback Asynchronously close a file and call the callback with the result code. -=item aio_read($fh,$offset,$length, $data,$dataoffset,$callback) +=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback -=item aio_write($fh,$offset,$length, $data,$dataoffset,$callback) +=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback Reads or writes C bytes from the specified C and C into the scalar given by C and offset C and calls the -callback without the actual number of bytes read (or undef on error). +callback without the actual number of bytes read (or C on error). -=item aio_stat($fh_or_path,$callback) +=item aio_stat $fh_or_path, $callback -=item aio_lstat($fh,$callback) +=item aio_lstat $fh, $callback -Works like perl's C or C in void context, i.e. the callback -will be called after the stat and the results will be available using -C or C<-s _> etc... +Works like perl's C or C in void context. The callback will +be called after the stat and the results will be available using C +or C<-s _> etc... Currently, the stats are always 64-bit-stats, i.e. instead of returning an error when stat'ing a large file, the results will be silently truncated unless perl itself is compiled with large file support. +=item aio_unlink $pathname, $callback + +Asynchronously unlink a file. + =cut +min_parallel 1; + END { max_parallel 0; } @@ -100,10 +139,10 @@ =head1 BUGS -This module has not yet been extensively tested. Watch out! +This module has been extensively tested in a large and very busy webserver +for many years now. - - perl-threads/fork interaction poorly tested. - - aio_open gives a fd, but all other functions expect a filehandle. + - aio_open gives a fd, but all other functions expect a perl filehandle. =head1 SEE ALSO @@ -111,8 +150,8 @@ =head1 AUTHOR - Marc Lehmann - http://www.goof.com/pcg/marc/ + Marc Lehmann + http://home.schmorp.de/ =cut