… | |
… | |
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> |
… | |
… | |
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 |
… | |
… | |
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 |
… | |
… | |
1312 | |
1357 | |
1313 | Event->io (fd => IO::AIO::poll_fileno, |
1358 | Event->io (fd => IO::AIO::poll_fileno, |
1314 | poll => 'r', async => 1, |
1359 | poll => 'r', async => 1, |
1315 | cb => \&IO::AIO::poll_cb); |
1360 | cb => \&IO::AIO::poll_cb); |
1316 | |
1361 | |
|
|
1362 | =item IO::AIO::poll_wait |
|
|
1363 | |
|
|
1364 | If there are any outstanding requests and none of them in the result |
|
|
1365 | phase, wait till the result filehandle becomes ready for reading (simply |
|
|
1366 | does a C<select> on the filehandle. This is useful if you want to |
|
|
1367 | synchronously wait for some requests to finish). |
|
|
1368 | |
|
|
1369 | See C<nreqs> for an example. |
|
|
1370 | |
|
|
1371 | =item IO::AIO::poll |
|
|
1372 | |
|
|
1373 | Waits until some requests have been handled. |
|
|
1374 | |
|
|
1375 | Returns the number of requests processed, but is otherwise strictly |
|
|
1376 | equivalent to: |
|
|
1377 | |
|
|
1378 | IO::AIO::poll_wait, IO::AIO::poll_cb |
|
|
1379 | |
|
|
1380 | =item IO::AIO::flush |
|
|
1381 | |
|
|
1382 | Wait till all outstanding AIO requests have been handled. |
|
|
1383 | |
|
|
1384 | Strictly equivalent to: |
|
|
1385 | |
|
|
1386 | IO::AIO::poll_wait, IO::AIO::poll_cb |
|
|
1387 | while IO::AIO::nreqs; |
|
|
1388 | |
1317 | =item IO::AIO::max_poll_reqs $nreqs |
1389 | =item IO::AIO::max_poll_reqs $nreqs |
1318 | |
1390 | |
1319 | =item IO::AIO::max_poll_time $seconds |
1391 | =item IO::AIO::max_poll_time $seconds |
1320 | |
1392 | |
1321 | These set the maximum number of requests (default C<0>, meaning infinity) |
1393 | These set the maximum number of requests (default C<0>, meaning infinity) |
… | |
… | |
1345 | # use a low priority so other tasks have priority |
1417 | # use a low priority so other tasks have priority |
1346 | Event->io (fd => IO::AIO::poll_fileno, |
1418 | Event->io (fd => IO::AIO::poll_fileno, |
1347 | poll => 'r', nice => 1, |
1419 | poll => 'r', nice => 1, |
1348 | cb => &IO::AIO::poll_cb); |
1420 | cb => &IO::AIO::poll_cb); |
1349 | |
1421 | |
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 |
1422 | =back |
1378 | |
1423 | |
1379 | =head3 CONTROLLING THE NUMBER OF THREADS |
1424 | =head3 CONTROLLING THE NUMBER OF THREADS |
1380 | |
1425 | |
1381 | =over |
1426 | =over |
… | |
… | |
1500 | C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. |
1545 | C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. |
1501 | |
1546 | |
1502 | On systems that do not implement C<posix_fadvise>, this function returns |
1547 | On systems that do not implement C<posix_fadvise>, this function returns |
1503 | ENOSYS, otherwise the return value of C<posix_fadvise>. |
1548 | ENOSYS, otherwise the return value of C<posix_fadvise>. |
1504 | |
1549 | |
|
|
1550 | =item IO::AIO::mlockall $flags |
|
|
1551 | |
|
|
1552 | Calls the C<mlockall> function with the given C<$flags> (a combination of |
|
|
1553 | C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>). |
|
|
1554 | |
|
|
1555 | On systems that do not implement C<mlockall>, this function returns |
|
|
1556 | ENOSYS, otherwise the return value of C<mlockall>. |
|
|
1557 | |
|
|
1558 | =item IO::AIO::munlockall |
|
|
1559 | |
|
|
1560 | Calls the C<munlockall> function. |
|
|
1561 | |
|
|
1562 | On systems that do not implement C<munlockall>, this function returns |
|
|
1563 | ENOSYS, otherwise the return value of C<munlockall>. |
|
|
1564 | |
1505 | =back |
1565 | =back |
1506 | |
1566 | |
1507 | =cut |
1567 | =cut |
1508 | |
1568 | |
1509 | min_parallel 8; |
1569 | min_parallel 8; |
1510 | |
1570 | |
1511 | END { flush } |
1571 | END { flush } |
1512 | |
1572 | |
1513 | 1; |
1573 | 1; |
|
|
1574 | |
|
|
1575 | =head1 EVENT LOOP INTEGRATION |
|
|
1576 | |
|
|
1577 | It is recommended to use L<AnyEvent::AIO> to integrate IO::AIO |
|
|
1578 | automatically into many event loops: |
|
|
1579 | |
|
|
1580 | # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...) |
|
|
1581 | use AnyEvent::AIO; |
|
|
1582 | |
|
|
1583 | You can also integrate IO::AIO manually into many event loops, here are |
|
|
1584 | some examples of how to do this: |
|
|
1585 | |
|
|
1586 | # EV integration |
|
|
1587 | my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; |
|
|
1588 | |
|
|
1589 | # Event integration |
|
|
1590 | Event->io (fd => IO::AIO::poll_fileno, |
|
|
1591 | poll => 'r', |
|
|
1592 | cb => \&IO::AIO::poll_cb); |
|
|
1593 | |
|
|
1594 | # Glib/Gtk2 integration |
|
|
1595 | add_watch Glib::IO IO::AIO::poll_fileno, |
|
|
1596 | in => sub { IO::AIO::poll_cb; 1 }; |
|
|
1597 | |
|
|
1598 | # Tk integration |
|
|
1599 | Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "", |
|
|
1600 | readable => \&IO::AIO::poll_cb); |
|
|
1601 | |
|
|
1602 | # Danga::Socket integration |
|
|
1603 | Danga::Socket->AddOtherFds (IO::AIO::poll_fileno => |
|
|
1604 | \&IO::AIO::poll_cb); |
1514 | |
1605 | |
1515 | =head2 FORK BEHAVIOUR |
1606 | =head2 FORK BEHAVIOUR |
1516 | |
1607 | |
1517 | This module should do "the right thing" when the process using it forks: |
1608 | This module should do "the right thing" when the process using it forks: |
1518 | |
1609 | |