… | |
… | |
168 | use common::sense; |
168 | use common::sense; |
169 | |
169 | |
170 | use base 'Exporter'; |
170 | use base 'Exporter'; |
171 | |
171 | |
172 | BEGIN { |
172 | BEGIN { |
173 | our $VERSION = '3.8'; |
173 | our $VERSION = '3.9'; |
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 |
… | |
… | |
368 | } else { |
368 | } else { |
369 | die "open failed: $!\n"; |
369 | die "open failed: $!\n"; |
370 | } |
370 | } |
371 | }; |
371 | }; |
372 | |
372 | |
|
|
373 | In addition to all the common open modes/flags (C<O_RDONLY>, C<O_WRONLY>, |
|
|
374 | C<O_RDWR>, C<O_CREAT>, C<O_TRUNC>, C<O_EXCL> and C<O_APPEND>), the |
|
|
375 | following POSIX and non-POSIX constants are available (missing ones on |
|
|
376 | your system are, as usual, C<0>): |
|
|
377 | |
|
|
378 | C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>, |
|
|
379 | C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>, |
|
|
380 | C<O_RSYNC>, C<O_SYNC> and C<O_TTY_INIT>. |
|
|
381 | |
373 | |
382 | |
374 | =item aio_close $fh, $callback->($status) |
383 | =item aio_close $fh, $callback->($status) |
375 | |
384 | |
376 | Asynchronously close a file and call the callback with the result |
385 | Asynchronously close a file and call the callback with the result |
377 | code. |
386 | code. |
… | |
… | |
692 | systems that do not deliver the inode information. |
701 | systems that do not deliver the inode information. |
693 | |
702 | |
694 | =item IO::AIO::READDIR_DIRS_FIRST |
703 | =item IO::AIO::READDIR_DIRS_FIRST |
695 | |
704 | |
696 | When this flag is set, then the names will be returned in an order where |
705 | When this flag is set, then the names will be returned in an order where |
697 | likely directories come first. This is useful when you need to quickly |
706 | likely directories come first, in optimal stat order. This is useful when |
698 | find directories, or you want to find all directories while avoiding to |
707 | you need to quickly find directories, or you want to find all directories |
699 | stat() each entry. |
708 | while avoiding to stat() each entry. |
700 | |
709 | |
701 | If the system returns type information in readdir, then this is used |
710 | If the system returns type information in readdir, then this is used |
702 | to find directories directly. Otherwise, likely directories are files |
711 | to find directories directly. Otherwise, likely directories are names |
703 | beginning with ".", or otherwise files with no dots, of which files with |
712 | beginning with ".", or otherwise names with no dots, of which names with |
704 | short names are tried first. |
713 | short names are tried first. |
705 | |
714 | |
706 | =item IO::AIO::READDIR_STAT_ORDER |
715 | =item IO::AIO::READDIR_STAT_ORDER |
707 | |
716 | |
708 | When this flag is set, then the names will be returned in an order |
717 | When this flag is set, then the names will be returned in an order |
… | |
… | |
1417 | |
1426 | |
1418 | If not all requests were processed for whatever reason, the filehandle |
1427 | If not all requests were processed for whatever reason, the filehandle |
1419 | will still be ready when C<poll_cb> returns, so normally you don't have to |
1428 | will still be ready when C<poll_cb> returns, so normally you don't have to |
1420 | do anything special to have it called later. |
1429 | do anything special to have it called later. |
1421 | |
1430 | |
|
|
1431 | Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes |
|
|
1432 | ready, it can be beneficial to call this function from loops which submit |
|
|
1433 | a lot of requests, to make sure the results get processed when they become |
|
|
1434 | available and not just when the loop is finished and the event loop takes |
|
|
1435 | over again. This function returns very fast when there are no outstanding |
|
|
1436 | requests. |
|
|
1437 | |
1422 | Example: Install an Event watcher that automatically calls |
1438 | Example: Install an Event watcher that automatically calls |
1423 | IO::AIO::poll_cb with high priority (more examples can be found in the |
1439 | IO::AIO::poll_cb with high priority (more examples can be found in the |
1424 | SYNOPSIS section, at the top of this document): |
1440 | SYNOPSIS section, at the top of this document): |
1425 | |
1441 | |
1426 | Event->io (fd => IO::AIO::poll_fileno, |
1442 | Event->io (fd => IO::AIO::poll_fileno, |
… | |
… | |
1548 | Sets the minimum idle timeout (default 10) after which worker threads are |
1564 | Sets the minimum idle timeout (default 10) after which worker threads are |
1549 | allowed to exit. SEe C<IO::AIO::max_idle>. |
1565 | allowed to exit. SEe C<IO::AIO::max_idle>. |
1550 | |
1566 | |
1551 | =item IO::AIO::max_outstanding $maxreqs |
1567 | =item IO::AIO::max_outstanding $maxreqs |
1552 | |
1568 | |
|
|
1569 | Sets the maximum number of outstanding requests to C<$nreqs>. If |
|
|
1570 | you do queue up more than this number of requests, the next call to |
|
|
1571 | C<IO::AIO::poll_cb> (and other functions calling C<poll_cb>, such as |
|
|
1572 | C<IO::AIO::flush> or C<IO::AIO::poll>) will block until the limit is no |
|
|
1573 | longer exceeded. |
|
|
1574 | |
|
|
1575 | In other words, this setting does not enforce a queue limit, but can be |
|
|
1576 | used to make poll functions block if the limit is exceeded. |
|
|
1577 | |
1553 | This is a very bad function to use in interactive programs because it |
1578 | This is a very bad function to use in interactive programs because it |
1554 | blocks, and a bad way to reduce concurrency because it is inexact: Better |
1579 | blocks, and a bad way to reduce concurrency because it is inexact: Better |
1555 | use an C<aio_group> together with a feed callback. |
1580 | use an C<aio_group> together with a feed callback. |
1556 | |
1581 | |
1557 | Sets the maximum number of outstanding requests to C<$nreqs>. If you |
1582 | It's main use is in scripts without an event loop - when you want to stat |
1558 | do queue up more than this number of requests, the next call to the |
1583 | a lot of files, you can write somehting like this: |
1559 | C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>) |
|
|
1560 | function will block until the limit is no longer exceeded. |
|
|
1561 | |
1584 | |
1562 | The default value is very large, so there is no practical limit on the |
1585 | IO::AIO::max_outstanding 32; |
1563 | number of outstanding requests. |
|
|
1564 | |
1586 | |
1565 | You can still queue as many requests as you want. Therefore, |
1587 | for my $path (...) { |
1566 | C<max_outstanding> is mainly useful in simple scripts (with low values) or |
1588 | aio_stat $path , ...; |
1567 | as a stop gap to shield against fatal memory overflow (with large values). |
1589 | IO::AIO::poll_cb; |
|
|
1590 | } |
|
|
1591 | |
|
|
1592 | IO::AIO::flush; |
|
|
1593 | |
|
|
1594 | The call to C<poll_cb> inside the loop will normally return instantly, but |
|
|
1595 | as soon as more thna C<32> reqeusts are in-flight, it will block until |
|
|
1596 | some requests have been handled. This keeps the loop from pushing a large |
|
|
1597 | number of C<aio_stat> requests onto the queue. |
|
|
1598 | |
|
|
1599 | The default value for C<max_outstanding> is very large, so there is no |
|
|
1600 | practical limit on the number of outstanding requests. |
1568 | |
1601 | |
1569 | =back |
1602 | =back |
1570 | |
1603 | |
1571 | =head3 STATISTICAL INFORMATION |
1604 | =head3 STATISTICAL INFORMATION |
1572 | |
1605 | |