… | |
… | |
25 | my $req = aio_unlink "/tmp/file", sub { }; |
25 | my $req = aio_unlink "/tmp/file", sub { }; |
26 | $req->cancel; # cancel request if still in queue |
26 | $req->cancel; # cancel request if still in queue |
27 | |
27 | |
28 | my $grp = aio_group sub { print "all stats done\n" }; |
28 | my $grp = aio_group sub { print "all stats done\n" }; |
29 | add $grp aio_stat "..." for ...; |
29 | add $grp aio_stat "..." for ...; |
30 | |
|
|
31 | # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...) |
|
|
32 | use AnyEvent::AIO; |
|
|
33 | |
|
|
34 | # EV integration |
|
|
35 | my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; |
|
|
36 | |
|
|
37 | # Event integration |
|
|
38 | Event->io (fd => IO::AIO::poll_fileno, |
|
|
39 | poll => 'r', |
|
|
40 | cb => \&IO::AIO::poll_cb); |
|
|
41 | |
|
|
42 | # Glib/Gtk2 integration |
|
|
43 | add_watch Glib::IO IO::AIO::poll_fileno, |
|
|
44 | in => sub { IO::AIO::poll_cb; 1 }; |
|
|
45 | |
|
|
46 | # Tk integration |
|
|
47 | Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "", |
|
|
48 | readable => \&IO::AIO::poll_cb); |
|
|
49 | |
|
|
50 | # Danga::Socket integration |
|
|
51 | Danga::Socket->AddOtherFds (IO::AIO::poll_fileno => |
|
|
52 | \&IO::AIO::poll_cb); |
|
|
53 | |
30 | |
54 | =head1 DESCRIPTION |
31 | =head1 DESCRIPTION |
55 | |
32 | |
56 | This module implements asynchronous I/O using whatever means your |
33 | This module implements asynchronous I/O using whatever means your |
57 | operating system supports. It is implemented as an interface to C<libeio> |
34 | operating system supports. It is implemented as an interface to C<libeio> |
… | |
… | |
191 | use common::sense; |
168 | use common::sense; |
192 | |
169 | |
193 | use base 'Exporter'; |
170 | use base 'Exporter'; |
194 | |
171 | |
195 | BEGIN { |
172 | BEGIN { |
196 | our $VERSION = '3.4'; |
173 | our $VERSION = '3.5'; |
197 | |
174 | |
198 | 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 |
199 | 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 |
200 | aio_scandir aio_symlink aio_readlink aio_sync aio_fsync |
177 | aio_scandir aio_symlink aio_readlink aio_sync aio_fsync |
201 | aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead |
178 | aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead |
… | |
… | |
219 | XSLoader::load ("IO::AIO", $VERSION); |
196 | XSLoader::load ("IO::AIO", $VERSION); |
220 | } |
197 | } |
221 | |
198 | |
222 | =head1 FUNCTIONS |
199 | =head1 FUNCTIONS |
223 | |
200 | |
|
|
201 | =head2 QUICK OVERVIEW |
|
|
202 | |
|
|
203 | This section simply lists the prototypes of the most important functions |
|
|
204 | for quick reference. See the following sections for function-by-function |
|
|
205 | documentation. |
|
|
206 | |
|
|
207 | aio_open $pathname, $flags, $mode, $callback->($fh) |
|
|
208 | aio_close $fh, $callback->($status) |
|
|
209 | aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) |
|
|
210 | aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) |
|
|
211 | aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) |
|
|
212 | aio_readahead $fh,$offset,$length, $callback->($retval) |
|
|
213 | aio_stat $fh_or_path, $callback->($status) |
|
|
214 | aio_lstat $fh, $callback->($status) |
|
|
215 | aio_statvfs $fh_or_path, $callback->($statvfs) |
|
|
216 | aio_utime $fh_or_path, $atime, $mtime, $callback->($status) |
|
|
217 | aio_chown $fh_or_path, $uid, $gid, $callback->($status) |
|
|
218 | aio_truncate $fh_or_path, $offset, $callback->($status) |
|
|
219 | aio_chmod $fh_or_path, $mode, $callback->($status) |
|
|
220 | aio_unlink $pathname, $callback->($status) |
|
|
221 | aio_mknod $path, $mode, $dev, $callback->($status) |
|
|
222 | aio_link $srcpath, $dstpath, $callback->($status) |
|
|
223 | aio_symlink $srcpath, $dstpath, $callback->($status) |
|
|
224 | aio_readlink $path, $callback->($link) |
|
|
225 | aio_rename $srcpath, $dstpath, $callback->($status) |
|
|
226 | aio_mkdir $pathname, $mode, $callback->($status) |
|
|
227 | aio_rmdir $pathname, $callback->($status) |
|
|
228 | aio_readdir $pathname, $callback->($entries) |
|
|
229 | aio_readdirx $pathname, $flags, $callback->($entries, $flags) |
|
|
230 | IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST |
|
|
231 | IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN |
|
|
232 | aio_load $path, $data, $callback->($status) |
|
|
233 | aio_copy $srcpath, $dstpath, $callback->($status) |
|
|
234 | aio_move $srcpath, $dstpath, $callback->($status) |
|
|
235 | aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) |
|
|
236 | aio_rmtree $path, $callback->($status) |
|
|
237 | aio_sync $callback->($status) |
|
|
238 | aio_fsync $fh, $callback->($status) |
|
|
239 | aio_fdatasync $fh, $callback->($status) |
|
|
240 | aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) |
|
|
241 | aio_pathsync $path, $callback->($status) |
|
|
242 | aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) |
|
|
243 | aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) |
|
|
244 | aio_group $callback->(...) |
|
|
245 | aio_nop $callback->() |
|
|
246 | |
|
|
247 | $prev_pri = aioreq_pri [$pri] |
|
|
248 | aioreq_nice $pri_adjust |
|
|
249 | |
|
|
250 | IO::AIO::poll_wait |
|
|
251 | IO::AIO::poll_cb |
|
|
252 | IO::AIO::poll |
|
|
253 | IO::AIO::flush |
|
|
254 | IO::AIO::max_poll_reqs $nreqs |
|
|
255 | IO::AIO::max_poll_time $seconds |
|
|
256 | IO::AIO::min_parallel $nthreads |
|
|
257 | IO::AIO::max_parallel $nthreads |
|
|
258 | IO::AIO::max_idle $nthreads |
|
|
259 | IO::AIO::max_outstanding $maxreqs |
|
|
260 | IO::AIO::nreqs |
|
|
261 | IO::AIO::nready |
|
|
262 | IO::AIO::npending |
|
|
263 | |
|
|
264 | IO::AIO::sendfile $ofh, $ifh, $offset, $count |
|
|
265 | IO::AIO::fadvise $fh, $offset, $len, $advice |
|
|
266 | IO::AIO::mlockall $flags |
|
|
267 | IO::AIO::munlockall |
|
|
268 | |
224 | =head2 AIO REQUEST FUNCTIONS |
269 | =head2 AIO REQUEST FUNCTIONS |
225 | |
270 | |
226 | All the C<aio_*> calls are more or less thin wrappers around the syscall |
271 | All the C<aio_*> calls are more or less thin wrappers around the syscall |
227 | with the same name (sans C<aio_>). The arguments are similar or identical, |
272 | with the same name (sans C<aio_>). The arguments are similar or identical, |
228 | and they all accept an additional (and optional) C<$callback> argument |
273 | and they all accept an additional (and optional) C<$callback> argument |
… | |
… | |
379 | than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each |
424 | than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each |
380 | other. |
425 | other. |
381 | |
426 | |
382 | This call tries to make use of a native C<sendfile> syscall to provide |
427 | This call tries to make use of a native C<sendfile> syscall to provide |
383 | zero-copy operation. For this to work, C<$out_fh> should refer to a |
428 | zero-copy operation. For this to work, C<$out_fh> should refer to a |
384 | socket, and C<$in_fh> should refer to mmap'able file. |
429 | socket, and C<$in_fh> should refer to an mmap'able file. |
385 | |
430 | |
386 | If a native sendfile cannot be found or it fails with C<ENOSYS>, |
431 | If a native sendfile cannot be found or it fails with C<ENOSYS>, |
387 | C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>, |
432 | C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>, |
388 | it will be emulated, so you can call C<aio_sendfile> on any type of |
433 | it will be emulated, so you can call C<aio_sendfile> on any type of |
389 | filehandle regardless of the limitations of the operating system. |
434 | filehandle regardless of the limitations of the operating system. |
… | |
… | |
432 | $_[0] and die "stat failed: $!"; |
477 | $_[0] and die "stat failed: $!"; |
433 | print "size is ", -s _, "\n"; |
478 | print "size is ", -s _, "\n"; |
434 | }; |
479 | }; |
435 | |
480 | |
436 | |
481 | |
437 | =item aio_statvfs $fh_or_path, $callback->($statvfs) |
482 | =item aio_statvfs $fh_or_path, $callback->($statvfs) |
438 | |
483 | |
439 | Works like the POSIX C<statvfs> or C<fstatvfs> syscalls, depending on |
484 | Works like the POSIX C<statvfs> or C<fstatvfs> syscalls, depending on |
440 | whether a file handle or path was passed. |
485 | whether a file handle or path was passed. |
441 | |
486 | |
442 | On success, the callback is passed a hash reference with the following |
487 | On success, the callback is passed a hash reference with the following |
… | |
… | |
1039 | } |
1084 | } |
1040 | |
1085 | |
1041 | =item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) |
1086 | =item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) |
1042 | |
1087 | |
1043 | This is a rather advanced IO::AIO call, which only works on mmap(2)ed |
1088 | This is a rather advanced IO::AIO call, which only works on mmap(2)ed |
1044 | scalars (see the L<Sys::Mmap> or L<Mmap> modules for details on this, note |
1089 | scalars (see the C<IO::AIO::mmap> function, although it also works on data |
|
|
1090 | scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the |
1045 | that the scalar must only be modified in-place while an aio operation is |
1091 | scalar must only be modified in-place while an aio operation is pending on |
1046 | pending on it). |
1092 | it). |
1047 | |
1093 | |
1048 | It calls the C<msync> function of your OS, if available, with the memory |
1094 | It calls the C<msync> function of your OS, if available, with the memory |
1049 | area starting at C<$offset> in the string and ending C<$length> bytes |
1095 | area starting at C<$offset> in the string and ending C<$length> bytes |
1050 | later. If C<$length> is negative, counts from the end, and if C<$length> |
1096 | later. If C<$length> is negative, counts from the end, and if C<$length> |
1051 | is C<undef>, then it goes till the end of the string. The flags can be |
1097 | is C<undef>, then it goes till the end of the string. The flags can be |
… | |
… | |
1312 | |
1358 | |
1313 | Event->io (fd => IO::AIO::poll_fileno, |
1359 | Event->io (fd => IO::AIO::poll_fileno, |
1314 | poll => 'r', async => 1, |
1360 | poll => 'r', async => 1, |
1315 | cb => \&IO::AIO::poll_cb); |
1361 | cb => \&IO::AIO::poll_cb); |
1316 | |
1362 | |
|
|
1363 | =item IO::AIO::poll_wait |
|
|
1364 | |
|
|
1365 | If there are any outstanding requests and none of them in the result |
|
|
1366 | phase, wait till the result filehandle becomes ready for reading (simply |
|
|
1367 | does a C<select> on the filehandle. This is useful if you want to |
|
|
1368 | synchronously wait for some requests to finish). |
|
|
1369 | |
|
|
1370 | See C<nreqs> for an example. |
|
|
1371 | |
|
|
1372 | =item IO::AIO::poll |
|
|
1373 | |
|
|
1374 | Waits until some requests have been handled. |
|
|
1375 | |
|
|
1376 | Returns the number of requests processed, but is otherwise strictly |
|
|
1377 | equivalent to: |
|
|
1378 | |
|
|
1379 | IO::AIO::poll_wait, IO::AIO::poll_cb |
|
|
1380 | |
|
|
1381 | =item IO::AIO::flush |
|
|
1382 | |
|
|
1383 | Wait till all outstanding AIO requests have been handled. |
|
|
1384 | |
|
|
1385 | Strictly equivalent to: |
|
|
1386 | |
|
|
1387 | IO::AIO::poll_wait, IO::AIO::poll_cb |
|
|
1388 | while IO::AIO::nreqs; |
|
|
1389 | |
1317 | =item IO::AIO::max_poll_reqs $nreqs |
1390 | =item IO::AIO::max_poll_reqs $nreqs |
1318 | |
1391 | |
1319 | =item IO::AIO::max_poll_time $seconds |
1392 | =item IO::AIO::max_poll_time $seconds |
1320 | |
1393 | |
1321 | These set the maximum number of requests (default C<0>, meaning infinity) |
1394 | These set the maximum number of requests (default C<0>, meaning infinity) |
… | |
… | |
1345 | # use a low priority so other tasks have priority |
1418 | # use a low priority so other tasks have priority |
1346 | Event->io (fd => IO::AIO::poll_fileno, |
1419 | Event->io (fd => IO::AIO::poll_fileno, |
1347 | poll => 'r', nice => 1, |
1420 | poll => 'r', nice => 1, |
1348 | cb => &IO::AIO::poll_cb); |
1421 | cb => &IO::AIO::poll_cb); |
1349 | |
1422 | |
1350 | =item IO::AIO::poll_wait |
|
|
1351 | |
|
|
1352 | If there are any outstanding requests and none of them in the result |
|
|
1353 | phase, wait till the result filehandle becomes ready for reading (simply |
|
|
1354 | does a C<select> on the filehandle. This is useful if you want to |
|
|
1355 | synchronously wait for some requests to finish). |
|
|
1356 | |
|
|
1357 | See C<nreqs> for an example. |
|
|
1358 | |
|
|
1359 | =item IO::AIO::poll |
|
|
1360 | |
|
|
1361 | Waits until some requests have been handled. |
|
|
1362 | |
|
|
1363 | Returns the number of requests processed, but is otherwise strictly |
|
|
1364 | equivalent to: |
|
|
1365 | |
|
|
1366 | IO::AIO::poll_wait, IO::AIO::poll_cb |
|
|
1367 | |
|
|
1368 | =item IO::AIO::flush |
|
|
1369 | |
|
|
1370 | Wait till all outstanding AIO requests have been handled. |
|
|
1371 | |
|
|
1372 | Strictly equivalent to: |
|
|
1373 | |
|
|
1374 | IO::AIO::poll_wait, IO::AIO::poll_cb |
|
|
1375 | while IO::AIO::nreqs; |
|
|
1376 | |
|
|
1377 | =back |
1423 | =back |
1378 | |
1424 | |
1379 | =head3 CONTROLLING THE NUMBER OF THREADS |
1425 | =head3 CONTROLLING THE NUMBER OF THREADS |
1380 | |
1426 | |
1381 | =over |
1427 | =over |
… | |
… | |
1500 | C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. |
1546 | C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. |
1501 | |
1547 | |
1502 | On systems that do not implement C<posix_fadvise>, this function returns |
1548 | On systems that do not implement C<posix_fadvise>, this function returns |
1503 | ENOSYS, otherwise the return value of C<posix_fadvise>. |
1549 | ENOSYS, otherwise the return value of C<posix_fadvise>. |
1504 | |
1550 | |
|
|
1551 | =item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] |
|
|
1552 | |
|
|
1553 | Memory-maps a file (or anonymous memory range) and attaches it to the |
|
|
1554 | given C<$scalar>, which will act like a string scalar. |
|
|
1555 | |
|
|
1556 | The only operations allowed on the scalar are C<substr>/C<vec> that don't |
|
|
1557 | change the string length, and most read-only operations such as copying it |
|
|
1558 | or searching it with regexes and so on. |
|
|
1559 | |
|
|
1560 | Anything else is unsafe and will, at best, result in memory leaks. |
|
|
1561 | |
|
|
1562 | The memory map associated with the C<$scalar> is automatically removed |
|
|
1563 | when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or |
|
|
1564 | C<IO::AIO::munmap> functions are called. |
|
|
1565 | |
|
|
1566 | This calls the C<mmap>(2) function internally. See your system's manual |
|
|
1567 | page for details on the C<$length>, C<$prot> and C<$flags> parameters. |
|
|
1568 | |
|
|
1569 | The C<$length> must be larger than zero and smaller than the actual |
|
|
1570 | filesize. |
|
|
1571 | |
|
|
1572 | C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>, |
|
|
1573 | C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>, |
|
|
1574 | |
|
|
1575 | C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or |
|
|
1576 | C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when |
|
|
1577 | not available, the are defined as 0): C<IO::AIO::MAP_ANONYMOUS> |
|
|
1578 | (which is set to C<MAP_ANON> if your system only provides this |
|
|
1579 | constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>, |
|
|
1580 | C<IO::AIO::MAP_NORESERVE>, C<IO::AIO::MAP_POPULATE> or |
|
|
1581 | C<IO::AIO::MAP_NONBLOCK> |
|
|
1582 | |
|
|
1583 | If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. |
|
|
1584 | |
|
|
1585 | =item IO::AIO::munmap $scalar |
|
|
1586 | |
|
|
1587 | Removes a previous mmap and undefines the C<$scalar>. |
|
|
1588 | |
|
|
1589 | =item IO::AIO::mlockall $flags |
|
|
1590 | |
|
|
1591 | Calls the C<mlockall> function with the given C<$flags> (a combination of |
|
|
1592 | C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>). |
|
|
1593 | |
|
|
1594 | On systems that do not implement C<mlockall>, this function returns |
|
|
1595 | ENOSYS, otherwise the return value of C<mlockall>. |
|
|
1596 | |
|
|
1597 | =item IO::AIO::munlockall |
|
|
1598 | |
|
|
1599 | Calls the C<munlockall> function. |
|
|
1600 | |
|
|
1601 | On systems that do not implement C<munlockall>, this function returns |
|
|
1602 | ENOSYS, otherwise the return value of C<munlockall>. |
|
|
1603 | |
1505 | =back |
1604 | =back |
1506 | |
1605 | |
1507 | =cut |
1606 | =cut |
1508 | |
1607 | |
1509 | min_parallel 8; |
1608 | min_parallel 8; |
1510 | |
1609 | |
1511 | END { flush } |
1610 | END { flush } |
1512 | |
1611 | |
1513 | 1; |
1612 | 1; |
|
|
1613 | |
|
|
1614 | =head1 EVENT LOOP INTEGRATION |
|
|
1615 | |
|
|
1616 | It is recommended to use L<AnyEvent::AIO> to integrate IO::AIO |
|
|
1617 | automatically into many event loops: |
|
|
1618 | |
|
|
1619 | # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...) |
|
|
1620 | use AnyEvent::AIO; |
|
|
1621 | |
|
|
1622 | You can also integrate IO::AIO manually into many event loops, here are |
|
|
1623 | some examples of how to do this: |
|
|
1624 | |
|
|
1625 | # EV integration |
|
|
1626 | my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; |
|
|
1627 | |
|
|
1628 | # Event integration |
|
|
1629 | Event->io (fd => IO::AIO::poll_fileno, |
|
|
1630 | poll => 'r', |
|
|
1631 | cb => \&IO::AIO::poll_cb); |
|
|
1632 | |
|
|
1633 | # Glib/Gtk2 integration |
|
|
1634 | add_watch Glib::IO IO::AIO::poll_fileno, |
|
|
1635 | in => sub { IO::AIO::poll_cb; 1 }; |
|
|
1636 | |
|
|
1637 | # Tk integration |
|
|
1638 | Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "", |
|
|
1639 | readable => \&IO::AIO::poll_cb); |
|
|
1640 | |
|
|
1641 | # Danga::Socket integration |
|
|
1642 | Danga::Socket->AddOtherFds (IO::AIO::poll_fileno => |
|
|
1643 | \&IO::AIO::poll_cb); |
1514 | |
1644 | |
1515 | =head2 FORK BEHAVIOUR |
1645 | =head2 FORK BEHAVIOUR |
1516 | |
1646 | |
1517 | This module should do "the right thing" when the process using it forks: |
1647 | This module should do "the right thing" when the process using it forks: |
1518 | |
1648 | |