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.185 by root, Sat Dec 11 19:06:07 2010 UTC vs.
Revision 1.192 by root, Fri May 20 00:00:03 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
… …
483for an explanation. 484for an explanation.
484 485
485Currently, 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
486error 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
487unless 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>.
488 498
489Example: Print the length of F</etc/passwd>: 499Example: Print the length of F</etc/passwd>:
490 500
491 aio_stat "/etc/passwd", sub { 501 aio_stat "/etc/passwd", sub {
492 $_[0] and die "stat failed: $!"; 502 $_[0] and die "stat failed: $!";
… …
594 604
595The only (POSIX-) portable way of calling this function is: 605The only (POSIX-) portable way of calling this function is:
596 606
597 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 607 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
598 608
609See C<aio_stat> for info about some potentially helpful extra constants
610and functions.
599 611
600=item aio_link $srcpath, $dstpath, $callback->($status) 612=item aio_link $srcpath, $dstpath, $callback->($status)
601 613
602Asynchronously 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
603the path C<$dstpath> and call the callback with the result code. 615the path C<$dstpath> and call the callback with the result code.
… …
656 668
657=over 4 669=over 4
658 670
659=item IO::AIO::READDIR_DENTS 671=item IO::AIO::READDIR_DENTS
660 672
661When this flag is off, then the callback gets an arrayref with of names 673When this flag is off, then the callback gets an arrayref consisting of
662only (as with C<aio_readdir>), otherwise it gets an arrayref with 674names only (as with C<aio_readdir>), otherwise it gets an arrayref with
663C<[$name, $type, $inode]> arrayrefs, each describing a single directory 675C<[$name, $type, $inode]> arrayrefs, each describing a single directory
664entry in more detail. 676entry in more detail.
665 677
666C<$name> is the name of the entry. 678C<$name> is the name of the entry.
667 679
… …
1394 1406
1395See C<poll_cb> for an example. 1407See C<poll_cb> for an example.
1396 1408
1397=item IO::AIO::poll_cb 1409=item IO::AIO::poll_cb
1398 1410
1399Process some outstanding events on the result pipe. You have to call this 1411Process some outstanding events on the result pipe. You have to call
1400regularly. Returns C<0> if all events could be processed, or C<-1> if it 1412this regularly. Returns C<0> if all events could be processed (or there
1401returned earlier for whatever reason. Returns immediately when no events 1413were no events to process), or C<-1> if it returned earlier for whatever
1402are outstanding. The amount of events processed depends on the settings of 1414reason. Returns immediately when no events are outstanding. The amount of
1403C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>. 1415events processed depends on the settings of C<IO::AIO::max_poll_req> and
1416C<IO::AIO::max_poll_time>.
1404 1417
1405If not all requests were processed for whatever reason, the filehandle 1418If not all requests were processed for whatever reason, the filehandle
1406will still be ready when C<poll_cb> returns, so normally you don't have to 1419will still be ready when C<poll_cb> returns, so normally you don't have to
1407do anything special to have it called later. 1420do anything special to have it called later.
1421
1422Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
1423ready, it can be beneficial to call this function from loops which submit
1424a lot of requests, to make sure the results get processed when they become
1425available and not just when the loop is finished and the event loop takes
1426over again. This function returns very fast when there are no outstanding
1427requests.
1408 1428
1409Example: Install an Event watcher that automatically calls 1429Example: Install an Event watcher that automatically calls
1410IO::AIO::poll_cb with high priority (more examples can be found in the 1430IO::AIO::poll_cb with high priority (more examples can be found in the
1411SYNOPSIS section, at the top of this document): 1431SYNOPSIS section, at the top of this document):
1412 1432
… …
1514 1534
1515Under normal circumstances you don't need to call this function. 1535Under normal circumstances you don't need to call this function.
1516 1536
1517=item IO::AIO::max_idle $nthreads 1537=item IO::AIO::max_idle $nthreads
1518 1538
1519Limit the number of threads (default: 4) that are allowed to idle (i.e., 1539Limit the number of threads (default: 4) that are allowed to idle
1520threads that did not get a request to process within 10 seconds). That 1540(i.e., threads that did not get a request to process within the idle
1521means if a thread becomes idle while C<$nthreads> other threads are also 1541timeout (default: 10 seconds). That means if a thread becomes idle while
1522idle, it will free its resources and exit. 1542C<$nthreads> other threads are also idle, it will free its resources and
1543exit.
1523 1544
1524This is useful when you allow a large number of threads (e.g. 100 or 1000) 1545This is useful when you allow a large number of threads (e.g. 100 or 1000)
1525to allow for extremely high load situations, but want to free resources 1546to allow for extremely high load situations, but want to free resources
1526under normal circumstances (1000 threads can easily consume 30MB of RAM). 1547under normal circumstances (1000 threads can easily consume 30MB of RAM).
1527 1548
1528The default is probably ok in most situations, especially if thread 1549The default is probably ok in most situations, especially if thread
1529creation is fast. If thread creation is very slow on your system you might 1550creation is fast. If thread creation is very slow on your system you might
1530want to use larger values. 1551want to use larger values.
1552
1553=item IO::AIO::idle_timeout $seconds
1554
1555Sets the minimum idle timeout (default 10) after which worker threads are
1556allowed to exit. SEe C<IO::AIO::max_idle>.
1531 1557
1532=item IO::AIO::max_outstanding $maxreqs 1558=item IO::AIO::max_outstanding $maxreqs
1533 1559
1534This is a very bad function to use in interactive programs because it 1560This is a very bad function to use in interactive programs because it
1535blocks, and a bad way to reduce concurrency because it is inexact: Better 1561blocks, and a bad way to reduce concurrency because it is inexact: Better

Diff Legend

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