ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/AIO.pm
(Generate patch)

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.184 by root, Mon Nov 1 22:03:43 2010 UTC vs.
Revision 1.189 by root, Sun Mar 27 10:26:08 2011 UTC

… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '3.7'; 173 our $VERSION = '3.8';
174 174
175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close 175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync 177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync
178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead 178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead
… …
182 aio_msync aio_mtouch aio_mlock aio_mlockall 182 aio_msync aio_mtouch aio_mlock aio_mlockall
183 aio_statvfs); 183 aio_statvfs);
184 184
185 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 185 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
186 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 186 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
187 min_parallel max_parallel max_idle 187 min_parallel max_parallel max_idle idle_timeout
188 nreqs nready npending nthreads 188 nreqs nready npending nthreads
189 max_poll_time max_poll_reqs 189 max_poll_time max_poll_reqs
190 sendfile fadvise madvise 190 sendfile fadvise madvise
191 mmap munmap munlock munlockall); 191 mmap munmap munlock munlockall);
192 192
… …
258 IO::AIO::max_poll_reqs $nreqs 258 IO::AIO::max_poll_reqs $nreqs
259 IO::AIO::max_poll_time $seconds 259 IO::AIO::max_poll_time $seconds
260 IO::AIO::min_parallel $nthreads 260 IO::AIO::min_parallel $nthreads
261 IO::AIO::max_parallel $nthreads 261 IO::AIO::max_parallel $nthreads
262 IO::AIO::max_idle $nthreads 262 IO::AIO::max_idle $nthreads
263 IO::AIO::idle_timeout $seconds
263 IO::AIO::max_outstanding $maxreqs 264 IO::AIO::max_outstanding $maxreqs
264 IO::AIO::nreqs 265 IO::AIO::nreqs
265 IO::AIO::nready 266 IO::AIO::nready
266 IO::AIO::npending 267 IO::AIO::npending
267 268
… …
428reading at byte offset C<$in_offset>, and starts writing at the current 429reading at byte offset C<$in_offset>, and starts writing at the current
429file offset of C<$out_fh>. Because of that, it is not safe to issue more 430file offset of C<$out_fh>. Because of that, it is not safe to issue more
430than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each 431than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
431other. 432other.
432 433
434Please note that C<aio_sendfile> can read more bytes from C<$in_fh> than
435are written, and there is no way to find out how many bytes have been read
436from C<aio_sendfile> alone, as C<aio_sendfile> only provides the number of
437bytes written to C<$out_fh>. Only if the result value equals C<$length>
438one can assume that C<$length> bytes have been read.
439
440Unlike with other C<aio_> functions, it makes a lot of sense to use
441C<aio_sendfile> on non-blocking sockets, as long as one end (typically
442the C<$in_fh>) is a file - the file I/O will then be asynchronous, while
443the socket I/O will be non-blocking. Note, however, that you can run into
444a trap where C<aio_sendfile> reads some data with readahead, then fails
445to write all data, and when the socket is ready the next time, the data
446in the cache is already lost, forcing C<aio_sendfile> to again hit the
447disk. Explicit C<aio_read> + C<aio_write> let's you control resource usage
448much better.
449
433This call tries to make use of a native C<sendfile> syscall to provide 450This call tries to make use of a native C<sendfile> syscall to provide
434zero-copy operation. For this to work, C<$out_fh> should refer to a 451zero-copy operation. For this to work, C<$out_fh> should refer to a
435socket, and C<$in_fh> should refer to an mmap'able file. 452socket, and C<$in_fh> should refer to an mmap'able file.
436 453
437If a native sendfile cannot be found or it fails with C<ENOSYS>, 454If a native sendfile cannot be found or it fails with C<ENOSYS>,
438C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>, 455C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>,
439it will be emulated, so you can call C<aio_sendfile> on any type of 456it will be emulated, so you can call C<aio_sendfile> on any type of
440filehandle regardless of the limitations of the operating system. 457filehandle regardless of the limitations of the operating system.
441
442Please note, however, that C<aio_sendfile> can read more bytes from
443C<$in_fh> than are written, and there is no way to find out how many
444bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
445provides the number of bytes written to C<$out_fh>. Only if the result
446value equals C<$length> one can assume that C<$length> bytes have been
447read.
448 458
449 459
450=item aio_readahead $fh,$offset,$length, $callback->($retval) 460=item aio_readahead $fh,$offset,$length, $callback->($retval)
451 461
452C<aio_readahead> populates the page cache with data from a file so that 462C<aio_readahead> populates the page cache with data from a file so that
… …
474for an explanation. 484for an explanation.
475 485
476Currently, the stats are always 64-bit-stats, i.e. instead of returning an 486Currently, the stats are always 64-bit-stats, i.e. instead of returning an
477error when stat'ing a large file, the results will be silently truncated 487error when stat'ing a large file, the results will be silently truncated
478unless perl itself is compiled with large file support. 488unless perl itself is compiled with large file support.
489
490To help interpret the mode and dev/rdev stat values, IO::AIO offers the
491following constants and functions (if not implemented, the constants will
492be C<0> and the functions will either C<croak> or fall back on traditional
493behaviour).
494
495C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
496C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
497C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
479 498
480Example: Print the length of F</etc/passwd>: 499Example: Print the length of F</etc/passwd>:
481 500
482 aio_stat "/etc/passwd", sub { 501 aio_stat "/etc/passwd", sub {
483 $_[0] and die "stat failed: $!"; 502 $_[0] and die "stat failed: $!";
… …
585 604
586The only (POSIX-) portable way of calling this function is: 605The only (POSIX-) portable way of calling this function is:
587 606
588 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 607 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
589 608
609See C<aio_stat> for info about some potentially helpful extra constants
610and functions.
590 611
591=item aio_link $srcpath, $dstpath, $callback->($status) 612=item aio_link $srcpath, $dstpath, $callback->($status)
592 613
593Asynchronously create a new link to the existing object at C<$srcpath> at 614Asynchronously create a new link to the existing object at C<$srcpath> at
594the path C<$dstpath> and call the callback with the result code. 615the path C<$dstpath> and call the callback with the result code.
… …
1505 1526
1506Under normal circumstances you don't need to call this function. 1527Under normal circumstances you don't need to call this function.
1507 1528
1508=item IO::AIO::max_idle $nthreads 1529=item IO::AIO::max_idle $nthreads
1509 1530
1510Limit the number of threads (default: 4) that are allowed to idle (i.e., 1531Limit the number of threads (default: 4) that are allowed to idle
1511threads that did not get a request to process within 10 seconds). That 1532(i.e., threads that did not get a request to process within the idle
1512means if a thread becomes idle while C<$nthreads> other threads are also 1533timeout (default: 10 seconds). That means if a thread becomes idle while
1513idle, it will free its resources and exit. 1534C<$nthreads> other threads are also idle, it will free its resources and
1535exit.
1514 1536
1515This is useful when you allow a large number of threads (e.g. 100 or 1000) 1537This is useful when you allow a large number of threads (e.g. 100 or 1000)
1516to allow for extremely high load situations, but want to free resources 1538to allow for extremely high load situations, but want to free resources
1517under normal circumstances (1000 threads can easily consume 30MB of RAM). 1539under normal circumstances (1000 threads can easily consume 30MB of RAM).
1518 1540
1519The default is probably ok in most situations, especially if thread 1541The default is probably ok in most situations, especially if thread
1520creation is fast. If thread creation is very slow on your system you might 1542creation is fast. If thread creation is very slow on your system you might
1521want to use larger values. 1543want to use larger values.
1544
1545=item IO::AIO::idle_timeout $seconds
1546
1547Sets the minimum idle timeout (default 10) after which worker threads are
1548allowed to exit. SEe C<IO::AIO::max_idle>.
1522 1549
1523=item IO::AIO::max_outstanding $maxreqs 1550=item IO::AIO::max_outstanding $maxreqs
1524 1551
1525This is a very bad function to use in interactive programs because it 1552This is a very bad function to use in interactive programs because it
1526blocks, and a bad way to reduce concurrency because it is inexact: Better 1553blocks, and a bad way to reduce concurrency because it is inexact: Better

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines