--- IO-AIO/AIO.pm 2010/09/12 03:40:05 1.183 +++ IO-AIO/AIO.pm 2011/05/19 22:42:20 1.190 @@ -170,7 +170,7 @@ use base 'Exporter'; BEGIN { - our $VERSION = '3.65'; + our $VERSION = '3.8'; our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx @@ -184,7 +184,7 @@ our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush - min_parallel max_parallel max_idle + min_parallel max_parallel max_idle idle_timeout nreqs nready npending nthreads max_poll_time max_poll_reqs sendfile fadvise madvise @@ -260,6 +260,7 @@ IO::AIO::min_parallel $nthreads IO::AIO::max_parallel $nthreads IO::AIO::max_idle $nthreads + IO::AIO::idle_timeout $seconds IO::AIO::max_outstanding $maxreqs IO::AIO::nreqs IO::AIO::nready @@ -267,6 +268,8 @@ IO::AIO::sendfile $ofh, $ifh, $offset, $count IO::AIO::fadvise $fh, $offset, $len, $advice + IO::AIO::madvise $scalar, $offset, $length, $advice + IO::AIO::mprotect $scalar, $offset, $length, $protect IO::AIO::munlock $scalar, $offset = 0, $length = undef IO::AIO::munlockall @@ -428,6 +431,22 @@ than one C per C<$out_fh>, as they will interfere with each other. +Please note that C 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 alone, as C 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. + +Unlike with other C functions, it makes a lot of sense to use +C on non-blocking sockets, as long as one end (typically +the C<$in_fh>) is a file - the file I/O will then be asynchronous, while +the socket I/O will be non-blocking. Note, however, that you can run into +a trap where C reads some data with readahead, then fails +to write all data, and when the socket is ready the next time, the data +in the cache is already lost, forcing C to again hit the +disk. Explicit C + C let's you control resource usage +much better. + This call tries to make use of a native C 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 an mmap'able file. @@ -437,13 +456,6 @@ it will be emulated, so you can call C on any type of filehandle regardless of the limitations of the operating system. -Please note, however, that C 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 alone, as C 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->($retval) @@ -475,6 +487,15 @@ error when stat'ing a large file, the results will be silently truncated unless perl itself is compiled with large file support. +To help interpret the mode and dev/rdev stat values, IO::AIO offers the +following constants and functions (if not implemented, the constants will +be C<0> and the functions will either C or fall back on traditional +behaviour). + +C, C, C, C, C, C, +C, C, C, C, +C, C. + Example: Print the length of F: aio_stat "/etc/passwd", sub { @@ -585,6 +606,8 @@ aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... +See C for info about some potentially helpful extra constants +and functions. =item aio_link $srcpath, $dstpath, $callback->($status) @@ -647,8 +670,8 @@ =item IO::AIO::READDIR_DENTS -When this flag is off, then the callback gets an arrayref with of names -only (as with C), otherwise it gets an arrayref with +When this flag is off, then the callback gets an arrayref consisting of +names only (as with C), otherwise it gets an arrayref with C<[$name, $type, $inode]> arrayrefs, each describing a single directory entry in more detail. @@ -1505,10 +1528,11 @@ =item IO::AIO::max_idle $nthreads -Limit the number of threads (default: 4) that are allowed to idle (i.e., -threads that did not get a request to process within 10 seconds). That -means if a thread becomes idle while C<$nthreads> other threads are also -idle, it will free its resources and exit. +Limit the number of threads (default: 4) that are allowed to idle +(i.e., threads that did not get a request to process within the idle +timeout (default: 10 seconds). That means if a thread becomes idle while +C<$nthreads> other threads are also idle, it will free its resources and +exit. This is useful when you allow a large number of threads (e.g. 100 or 1000) to allow for extremely high load situations, but want to free resources @@ -1518,6 +1542,11 @@ creation is fast. If thread creation is very slow on your system you might want to use larger values. +=item IO::AIO::idle_timeout $seconds + +Sets the minimum idle timeout (default 10) after which worker threads are +allowed to exit. SEe C. + =item IO::AIO::max_outstanding $maxreqs This is a very bad function to use in interactive programs because it @@ -1582,7 +1611,7 @@ =item IO::AIO::fadvise $fh, $offset, $len, $advice -Simply calls the C function (see it's +Simply calls the C function (see its manpage for details). The following advice constants are avaiable: C, C, C, C, @@ -1591,6 +1620,26 @@ On systems that do not implement C, this function returns ENOSYS, otherwise the return value of C. +=item IO::AIO::madvise $scalar, $offset, $len, $advice + +Simply calls the C function (see its +manpage for details). The following advice constants are +avaiable: C, C, +C, C, C. + +On systems that do not implement C, this function returns +ENOSYS, otherwise the return value of C. + +=item IO::AIO::mprotect $scalar, $offset, $len, $protect + +Simply calls the C function on the preferably AIO::mmap'ed +$scalar (see its manpage for details). The following protect +constants are avaiable: C, C, +C, C. + +On systems that do not implement C, this function returns +ENOSYS, otherwise the return value of C. + =item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] Memory-maps a file (or anonymous memory range) and attaches it to the