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.159 by root, Tue Jun 30 07:33:58 2009 UTC vs.
Revision 1.175 by root, Sun Jan 10 20:37:33 2010 UTC

… …
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
56This module implements asynchronous I/O using whatever means your 33This module implements asynchronous I/O using whatever means your
57operating system supports. It is implemented as an interface to C<libeio> 34operating system supports. It is implemented as an interface to C<libeio>
… …
186 163
187package IO::AIO; 164package IO::AIO;
188 165
189use Carp (); 166use Carp ();
190 167
191no warnings; 168use common::sense;
192use strict 'vars';
193 169
194use base 'Exporter'; 170use base 'Exporter';
195 171
196BEGIN { 172BEGIN {
197 our $VERSION = '3.26'; 173 our $VERSION = '3.5';
198 174
199 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
200 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
201 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync 177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync
202 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead 178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead
203 aio_rename aio_link aio_move aio_copy aio_group 179 aio_rename aio_link aio_move aio_copy aio_group
204 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown 180 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
205 aio_chmod aio_utime aio_truncate); 181 aio_chmod aio_utime aio_truncate
182 aio_msync aio_mtouch aio_statvfs);
206 183
207 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 184 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
208 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 185 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
209 min_parallel max_parallel max_idle 186 min_parallel max_parallel max_idle
210 nreqs nready npending nthreads 187 nreqs nready npending nthreads
… …
218 require XSLoader; 195 require XSLoader;
219 XSLoader::load ("IO::AIO", $VERSION); 196 XSLoader::load ("IO::AIO", $VERSION);
220} 197}
221 198
222=head1 FUNCTIONS 199=head1 FUNCTIONS
200
201=head2 QUICK OVERVIEW
202
203This section simply lists the prototypes of the most important functions
204for quick reference. See the following sections for function-by-function
205documentation.
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
223 268
224=head2 AIO REQUEST FUNCTIONS 269=head2 AIO REQUEST FUNCTIONS
225 270
226All the C<aio_*> calls are more or less thin wrappers around the syscall 271All the C<aio_*> calls are more or less thin wrappers around the syscall
227with the same name (sans C<aio_>). The arguments are similar or identical, 272with the same name (sans C<aio_>). The arguments are similar or identical,
… …
381 426
382This call tries to make use of a native C<sendfile> syscall to provide 427This call tries to make use of a native C<sendfile> syscall to provide
383zero-copy operation. For this to work, C<$out_fh> should refer to a 428zero-copy operation. For this to work, C<$out_fh> should refer to a
384socket, and C<$in_fh> should refer to mmap'able file. 429socket, and C<$in_fh> should refer to mmap'able file.
385 430
386If the native sendfile call fails or is not implemented, it will be 431If a native sendfile cannot be found or it fails with C<ENOSYS>,
432C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>,
387emulated, so you can call C<aio_sendfile> on any type of filehandle 433it will be emulated, so you can call C<aio_sendfile> on any type of
388regardless of the limitations of the operating system. 434filehandle regardless of the limitations of the operating system.
389 435
390Please note, however, that C<aio_sendfile> can read more bytes from 436Please note, however, that C<aio_sendfile> can read more bytes from
391C<$in_fh> than are written, and there is no way to find out how many 437C<$in_fh> than are written, and there is no way to find out how many
392bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only 438bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
393provides the number of bytes written to C<$out_fh>. Only if the result 439provides the number of bytes written to C<$out_fh>. Only if the result
… …
431 $_[0] and die "stat failed: $!"; 477 $_[0] and die "stat failed: $!";
432 print "size is ", -s _, "\n"; 478 print "size is ", -s _, "\n";
433 }; 479 };
434 480
435 481
482=item aio_statvfs $fh_or_path, $callback->($statvfs)
483
484Works like the POSIX C<statvfs> or C<fstatvfs> syscalls, depending on
485whether a file handle or path was passed.
486
487On success, the callback is passed a hash reference with the following
488members: C<bsize>, C<frsize>, C<blocks>, C<bfree>, C<bavail>, C<files>,
489C<ffree>, C<favail>, C<fsid>, C<flag> and C<namemax>. On failure, C<undef>
490is passed.
491
492The following POSIX IO::AIO::ST_* constants are defined: C<ST_RDONLY> and
493C<ST_NOSUID>.
494
495The following non-POSIX IO::AIO::ST_* flag masks are defined to
496their correct value when available, or to C<0> on systems that do
497not support them: C<ST_NODEV>, C<ST_NOEXEC>, C<ST_SYNCHRONOUS>,
498C<ST_MANDLOCK>, C<ST_WRITE>, C<ST_APPEND>, C<ST_IMMUTABLE>, C<ST_NOATIME>,
499C<ST_NODIRATIME> and C<ST_RELATIME>.
500
501Example: stat C</wd> and dump out the data if successful.
502
503 aio_statvfs "/wd", sub {
504 my $f = $_[0]
505 or die "statvfs: $!";
506
507 use Data::Dumper;
508 say Dumper $f;
509 };
510
511 # result:
512 {
513 bsize => 1024,
514 bfree => 4333064312,
515 blocks => 10253828096,
516 files => 2050765568,
517 flag => 4096,
518 favail => 2042092649,
519 bavail => 4333064312,
520 ffree => 2042092649,
521 namemax => 255,
522 frsize => 1024,
523 fsid => 1810
524 }
525
526
436=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 527=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
437 528
438Works like perl's C<utime> function (including the special case of $atime 529Works like perl's C<utime> function (including the special case of $atime
439and $mtime being undef). Fractional times are supported if the underlying 530and $mtime being undef). Fractional times are supported if the underlying
440syscalls support them. 531syscalls support them.
… …
635 726
636=item aio_copy $srcpath, $dstpath, $callback->($status) 727=item aio_copy $srcpath, $dstpath, $callback->($status)
637 728
638Try to copy the I<file> (directories not supported as either source or 729Try to copy the I<file> (directories not supported as either source or
639destination) from C<$srcpath> to C<$dstpath> and call the callback with 730destination) from C<$srcpath> to C<$dstpath> and call the callback with
640the C<0> (error) or C<-1> ok. 731a status of C<0> (ok) or C<-1> (error, see C<$!>).
641 732
642This is a composite request that creates the destination file with 733This is a composite request that creates the destination file with
643mode 0200 and copies the contents of the source file into it using 734mode 0200 and copies the contents of the source file into it using
644C<aio_sendfile>, followed by restoring atime, mtime, access mode and 735C<aio_sendfile>, followed by restoring atime, mtime, access mode and
645uid/gid, in that order. 736uid/gid, in that order.
… …
657 my $grp = aio_group $cb; 748 my $grp = aio_group $cb;
658 749
659 aioreq_pri $pri; 750 aioreq_pri $pri;
660 add $grp aio_open $src, O_RDONLY, 0, sub { 751 add $grp aio_open $src, O_RDONLY, 0, sub {
661 if (my $src_fh = $_[0]) { 752 if (my $src_fh = $_[0]) {
662 my @stat = stat $src_fh; # hmm, might bock over nfs? 753 my @stat = stat $src_fh; # hmm, might block over nfs?
663 754
664 aioreq_pri $pri; 755 aioreq_pri $pri;
665 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub { 756 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
666 if (my $dst_fh = $_[0]) { 757 if (my $dst_fh = $_[0]) {
667 aioreq_pri $pri; 758 aioreq_pri $pri;
… …
714 805
715=item aio_move $srcpath, $dstpath, $callback->($status) 806=item aio_move $srcpath, $dstpath, $callback->($status)
716 807
717Try to move the I<file> (directories not supported as either source or 808Try to move the I<file> (directories not supported as either source or
718destination) from C<$srcpath> to C<$dstpath> and call the callback with 809destination) from C<$srcpath> to C<$dstpath> and call the callback with
719the C<0> (error) or C<-1> ok. 810a status of C<0> (ok) or C<-1> (error, see C<$!>).
720 811
721This is a composite request that tries to rename(2) the file first; if 812This is a composite request that tries to rename(2) the file first; if
722rename fails with C<EXDEV>, it copies the file with C<aio_copy> and, if 813rename fails with C<EXDEV>, it copies the file with C<aio_copy> and, if
723that is successful, unlinks the C<$srcpath>. 814that is successful, unlinks the C<$srcpath>.
724 815
… …
958(E.g. rename). This might not work on all operating systems or have any 1049(E.g. rename). This might not work on all operating systems or have any
959specific effect, but usually it makes sure that directory changes get 1050specific effect, but usually it makes sure that directory changes get
960written to disc. It works for anything that can be opened for read-only, 1051written to disc. It works for anything that can be opened for read-only,
961not just directories. 1052not just directories.
962 1053
1054Future versions of this function might fall back to other methods when
1055C<fsync> on the directory fails (such as calling C<sync>).
1056
963Passes C<0> when everything went ok, and C<-1> on error. 1057Passes C<0> when everything went ok, and C<-1> on error.
964 1058
965=cut 1059=cut
966 1060
967sub aio_pathsync($;$) { 1061sub aio_pathsync($;$) {
… …
987 }; 1081 };
988 1082
989 $grp 1083 $grp
990} 1084}
991 1085
1086=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1087
1088This is a rather advanced IO::AIO call, which only works on mmap(2)ed
1089scalars (see the L<Sys::Mmap> or L<Mmap> modules for details on this, note
1090that the scalar must only be modified in-place while an aio operation is
1091pending on it).
1092
1093It calls the C<msync> function of your OS, if available, with the memory
1094area starting at C<$offset> in the string and ending C<$length> bytes
1095later. If C<$length> is negative, counts from the end, and if C<$length>
1096is C<undef>, then it goes till the end of the string. The flags can be
1097a combination of C<IO::AIO::MS_ASYNC>, C<IO::AIO::MS_INVALIDATE> and
1098C<IO::AIO::MS_SYNC>.
1099
1100=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1101
1102This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1103scalars.
1104
1105It touches (reads or writes) all memory pages in the specified
1106range inside the scalar. All caveats and parameters are the same
1107as for C<aio_msync>, above, except for flags, which must be either
1108C<0> (which reads all pages and ensures they are instantiated) or
1109C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and
1110writing an octet from it, which dirties the page).
1111
992=item aio_group $callback->(...) 1112=item aio_group $callback->(...)
993 1113
994This is a very special aio request: Instead of doing something, it is a 1114This is a very special aio request: Instead of doing something, it is a
995container for other aio requests, which is useful if you want to bundle 1115container for other aio requests, which is useful if you want to bundle
996many requests into a single, composite, request with a definite callback 1116many requests into a single, composite, request with a definite callback
… …
1131=item $grp->cancel_subs 1251=item $grp->cancel_subs
1132 1252
1133Cancel all subrequests and clears any feeder, but not the group request 1253Cancel all subrequests and clears any feeder, but not the group request
1134itself. Useful when you queued a lot of events but got a result early. 1254itself. Useful when you queued a lot of events but got a result early.
1135 1255
1256The group request will finish normally (you cannot add requests to the
1257group).
1258
1136=item $grp->result (...) 1259=item $grp->result (...)
1137 1260
1138Set the result value(s) that will be passed to the group callback when all 1261Set the result value(s) that will be passed to the group callback when all
1139subrequests have finished and set the groups errno to the current value 1262subrequests have finished and set the groups errno to the current value
1140of errno (just like calling C<errno> without an error number). By default, 1263of errno (just like calling C<errno> without an error number). By default,
… …
1234 1357
1235 Event->io (fd => IO::AIO::poll_fileno, 1358 Event->io (fd => IO::AIO::poll_fileno,
1236 poll => 'r', async => 1, 1359 poll => 'r', async => 1,
1237 cb => \&IO::AIO::poll_cb); 1360 cb => \&IO::AIO::poll_cb);
1238 1361
1362=item IO::AIO::poll_wait
1363
1364If there are any outstanding requests and none of them in the result
1365phase, wait till the result filehandle becomes ready for reading (simply
1366does a C<select> on the filehandle. This is useful if you want to
1367synchronously wait for some requests to finish).
1368
1369See C<nreqs> for an example.
1370
1371=item IO::AIO::poll
1372
1373Waits until some requests have been handled.
1374
1375Returns the number of requests processed, but is otherwise strictly
1376equivalent to:
1377
1378 IO::AIO::poll_wait, IO::AIO::poll_cb
1379
1380=item IO::AIO::flush
1381
1382Wait till all outstanding AIO requests have been handled.
1383
1384Strictly equivalent to:
1385
1386 IO::AIO::poll_wait, IO::AIO::poll_cb
1387 while IO::AIO::nreqs;
1388
1239=item IO::AIO::max_poll_reqs $nreqs 1389=item IO::AIO::max_poll_reqs $nreqs
1240 1390
1241=item IO::AIO::max_poll_time $seconds 1391=item IO::AIO::max_poll_time $seconds
1242 1392
1243These set the maximum number of requests (default C<0>, meaning infinity) 1393These set the maximum number of requests (default C<0>, meaning infinity)
… …
1267 # use a low priority so other tasks have priority 1417 # use a low priority so other tasks have priority
1268 Event->io (fd => IO::AIO::poll_fileno, 1418 Event->io (fd => IO::AIO::poll_fileno,
1269 poll => 'r', nice => 1, 1419 poll => 'r', nice => 1,
1270 cb => &IO::AIO::poll_cb); 1420 cb => &IO::AIO::poll_cb);
1271 1421
1272=item IO::AIO::poll_wait
1273
1274If there are any outstanding requests and none of them in the result
1275phase, wait till the result filehandle becomes ready for reading (simply
1276does a C<select> on the filehandle. This is useful if you want to
1277synchronously wait for some requests to finish).
1278
1279See C<nreqs> for an example.
1280
1281=item IO::AIO::poll
1282
1283Waits until some requests have been handled.
1284
1285Returns the number of requests processed, but is otherwise strictly
1286equivalent to:
1287
1288 IO::AIO::poll_wait, IO::AIO::poll_cb
1289
1290=item IO::AIO::flush
1291
1292Wait till all outstanding AIO requests have been handled.
1293
1294Strictly equivalent to:
1295
1296 IO::AIO::poll_wait, IO::AIO::poll_cb
1297 while IO::AIO::nreqs;
1298
1299=back 1422=back
1300 1423
1301=head3 CONTROLLING THE NUMBER OF THREADS 1424=head3 CONTROLLING THE NUMBER OF THREADS
1302 1425
1303=over 1426=over
… …
1422C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 1545C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1423 1546
1424On systems that do not implement C<posix_fadvise>, this function returns 1547On systems that do not implement C<posix_fadvise>, this function returns
1425ENOSYS, otherwise the return value of C<posix_fadvise>. 1548ENOSYS, otherwise the return value of C<posix_fadvise>.
1426 1549
1550=item IO::AIO::mlockall $flags
1551
1552Calls the C<mlockall> function with the given C<$flags> (a combination of
1553C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>).
1554
1555On systems that do not implement C<mlockall>, this function returns
1556ENOSYS, otherwise the return value of C<mlockall>.
1557
1558=item IO::AIO::munlockall
1559
1560Calls the C<munlockall> function.
1561
1562On systems that do not implement C<munlockall>, this function returns
1563ENOSYS, otherwise the return value of C<munlockall>.
1564
1427=back 1565=back
1428 1566
1429=cut 1567=cut
1430 1568
1431min_parallel 8; 1569min_parallel 8;
1432 1570
1433END { flush } 1571END { flush }
1434 1572
14351; 15731;
1574
1575=head1 EVENT LOOP INTEGRATION
1576
1577It is recommended to use L<AnyEvent::AIO> to integrate IO::AIO
1578automatically into many event loops:
1579
1580 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
1581 use AnyEvent::AIO;
1582
1583You can also integrate IO::AIO manually into many event loops, here are
1584some 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);
1436 1605
1437=head2 FORK BEHAVIOUR 1606=head2 FORK BEHAVIOUR
1438 1607
1439This module should do "the right thing" when the process using it forks: 1608This module should do "the right thing" when the process using it forks:
1440 1609

Diff Legend

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