--- IO-AIO/README 2005/07/10 17:07:44 1.1 +++ IO-AIO/README 2005/07/10 20:57:36 1.3 @@ -6,16 +6,20 @@ 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. + is currently not reentrant, so use appropriate locking yourself. API NOTES All the "aio_*" calls are more or less thin wrappers around the syscall @@ -39,12 +43,14 @@ 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 + 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). + (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 module automatically starts a single async thread. + this module automatically starts some threads (the exact number + might change, and is currently 4). IO::AIO::max_parallel $nthreads Sets the maximum number of AIO threads to $nthreads. If more than @@ -57,6 +63,17 @@ Under normal circumstances you don't need to call this function. + $oldnreqs = IO::AIO::max_outstanding $nreqs + Sets the maximum number of outstanding requests to $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 this to a relatively low number, such as 100. + + Under normal circumstances you don't need to call this function. + $fileno = IO::AIO::poll_fileno Return the *request result pipe filehandle*. This filehandle must be polled for reading by some mechanism outside this module (e.g. Event @@ -92,9 +109,11 @@ while IO::AIO::nreqs; 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 "aio_open" must be absolute. See API NOTES, + above, for an explanation. The $mode argument is a bitmask. See the "Fcntl" module for a list. They are the same as used in "sysopen". @@ -102,10 +121,8 @@ 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"; @@ -114,7 +131,10 @@ aio_close $fh, $callback Asynchronously close a file and call the callback with the result - code. + code. *WARNING:* although accepted, you should not pass in a perl + filehandle here, as perl will likely close the file descriptor + itself when the filehandle is destroyed. Normally, you can safely + call perls "close" or just let filehandles go out of scope. aio_read $fh,$offset,$length, $data,$dataoffset,$callback aio_write $fh,$offset,$length, $data,$dataoffset,$callback @@ -133,7 +153,8 @@ aio_readahead $fh,$offset,$length, $callback Asynchronously reads the specified byte range into the page cache, - using the "readahead" syscall. + using the "readahead" syscall. If that syscall doesn't exist the + status will be -1 and $! is set to ENOSYS. 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 @@ -179,13 +200,10 @@ callback with the fdatasync result code. BUGS - This module has been extensively tested in a large and very busy - webserver for many years now. - - - aio_open gives a fd, but all other functions expect a perl filehandle. + - could be optimized to use more semaphores instead of filehandles. SEE ALSO - Coro. + Coro, Linux::AIO. AUTHOR Marc Lehmann