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.231 by root, Fri Jul 27 19:03:18 2012 UTC vs.
Revision 1.248 by root, Sun Jul 27 22:10:53 2014 UTC

68=head2 EXAMPLE 68=head2 EXAMPLE
69 69
70This is a simple example that uses the EV module and loads 70This is a simple example that uses the EV module and loads
71F</etc/passwd> asynchronously: 71F</etc/passwd> asynchronously:
72 72
73 use Fcntl;
74 use EV; 73 use EV;
75 use IO::AIO; 74 use IO::AIO;
76 75
77 # register the IO::AIO callback with EV 76 # register the IO::AIO callback with EV
78 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 77 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
168use common::sense; 167use common::sense;
169 168
170use base 'Exporter'; 169use base 'Exporter';
171 170
172BEGIN { 171BEGIN {
173 our $VERSION = '4.15'; 172 our $VERSION = 4.31;
174 173
175 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close 174 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 175 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync 176 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
178 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_fallocate 177 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_allocate
179 aio_pathsync aio_readahead aio_fiemap 178 aio_pathsync aio_readahead aio_fiemap
180 aio_rename aio_link aio_move aio_copy aio_group 179 aio_rename aio_link aio_move aio_copy aio_group
181 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
182 aio_chmod aio_utime aio_truncate 181 aio_chmod aio_utime aio_truncate
183 aio_msync aio_mtouch aio_mlock aio_mlockall 182 aio_msync aio_mtouch aio_mlock aio_mlockall
362 361
363 362
364=item aio_open $pathname, $flags, $mode, $callback->($fh) 363=item aio_open $pathname, $flags, $mode, $callback->($fh)
365 364
366Asynchronously open or create a file and call the callback with a newly 365Asynchronously open or create a file and call the callback with a newly
367created filehandle for the file. 366created filehandle for the file (or C<undef> in case of an error).
368 367
369The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 368The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
370for an explanation. 369for an explanation.
371 370
372The C<$flags> argument is a bitmask. See the C<Fcntl> module for a 371The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
603 namemax => 255, 602 namemax => 255,
604 frsize => 1024, 603 frsize => 1024,
605 fsid => 1810 604 fsid => 1810
606 } 605 }
607 606
607Here is a (likely partial - send me updates!) list of fsid values used by
608Linux - it is safe to hardcode these when C<$^O> is C<linux>:
609
610 0x0000adf5 adfs
611 0x0000adff affs
612 0x5346414f afs
613 0x09041934 anon-inode filesystem
614 0x00000187 autofs
615 0x42465331 befs
616 0x1badface bfs
617 0x42494e4d binfmt_misc
618 0x9123683e btrfs
619 0x0027e0eb cgroupfs
620 0xff534d42 cifs
621 0x73757245 coda
622 0x012ff7b7 coh
623 0x28cd3d45 cramfs
624 0x453dcd28 cramfs-wend (wrong endianness)
625 0x64626720 debugfs
626 0x00001373 devfs
627 0x00001cd1 devpts
628 0x0000f15f ecryptfs
629 0x00414a53 efs
630 0x0000137d ext
631 0x0000ef53 ext2/ext3
632 0x0000ef51 ext2
633 0x00004006 fat
634 0x65735546 fuseblk
635 0x65735543 fusectl
636 0x0bad1dea futexfs
637 0x01161970 gfs2
638 0x47504653 gpfs
639 0x00004244 hfs
640 0xf995e849 hpfs
641 0x958458f6 hugetlbfs
642 0x2bad1dea inotifyfs
643 0x00009660 isofs
644 0x000072b6 jffs2
645 0x3153464a jfs
646 0x6b414653 k-afs
647 0x0bd00bd0 lustre
648 0x0000137f minix
649 0x0000138f minix 30 char names
650 0x00002468 minix v2
651 0x00002478 minix v2 30 char names
652 0x00004d5a minix v3
653 0x19800202 mqueue
654 0x00004d44 msdos
655 0x0000564c novell
656 0x00006969 nfs
657 0x6e667364 nfsd
658 0x00003434 nilfs
659 0x5346544e ntfs
660 0x00009fa1 openprom
661 0x7461636F ocfs2
662 0x00009fa0 proc
663 0x6165676c pstorefs
664 0x0000002f qnx4
665 0x858458f6 ramfs
666 0x52654973 reiserfs
667 0x00007275 romfs
668 0x67596969 rpc_pipefs
669 0x73636673 securityfs
670 0xf97cff8c selinux
671 0x0000517b smb
672 0x534f434b sockfs
673 0x73717368 squashfs
674 0x62656572 sysfs
675 0x012ff7b6 sysv2
676 0x012ff7b5 sysv4
677 0x01021994 tmpfs
678 0x15013346 udf
679 0x00011954 ufs
680 0x54190100 ufs byteswapped
681 0x00009fa2 usbdevfs
682 0x01021997 v9fs
683 0xa501fcf5 vxfs
684 0xabba1974 xenfs
685 0x012ff7b4 xenix
686 0x58465342 xfs
687 0x012fd16d xia
608 688
609=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 689=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
610 690
611Works like perl's C<utime> function (including the special case of $atime 691Works like perl's C<utime> function (including the special case of $atime
612and $mtime being undef). Fractional times are supported if the underlying 692and $mtime being undef). Fractional times are supported if the underlying
702 782
703 783
704=item aio_realpath $pathname, $callback->($path) 784=item aio_realpath $pathname, $callback->($path)
705 785
706Asynchronously make the path absolute and resolve any symlinks in 786Asynchronously make the path absolute and resolve any symlinks in
707C<$path>. The resulting path only consists of directories (Same as 787C<$path>. The resulting path only consists of directories (same as
708L<Cwd::realpath>). 788L<Cwd::realpath>).
709 789
710This request can be used to get the absolute path of the current working 790This request can be used to get the absolute path of the current working
711directory by passing it a path of F<.> (a single dot). 791directory by passing it a path of F<.> (a single dot).
712 792
713 793
714=item aio_rename $srcpath, $dstpath, $callback->($status) 794=item aio_rename $srcpath, $dstpath, $callback->($status)
715 795
716Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 796Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
717rename(2) and call the callback with the result code. 797rename(2) and call the callback with the result code.
798
799On systems that support the AIO::WD working directory abstraction
800natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
801of failing, C<rename> is called on the absolute path of C<$wd>.
718 802
719 803
720=item aio_mkdir $pathname, $mode, $callback->($status) 804=item aio_mkdir $pathname, $mode, $callback->($status)
721 805
722Asynchronously mkdir (create) a directory and call the callback with 806Asynchronously mkdir (create) a directory and call the callback with
726 810
727=item aio_rmdir $pathname, $callback->($status) 811=item aio_rmdir $pathname, $callback->($status)
728 812
729Asynchronously rmdir (delete) a directory and call the callback with the 813Asynchronously rmdir (delete) a directory and call the callback with the
730result code. 814result code.
815
816On systems that support the AIO::WD working directory abstraction
817natively, the case C<[$wd, "."]> is specialcased - instead of failing,
818C<rmdir> is called on the absolute path of C<$wd>.
731 819
732 820
733=item aio_readdir $pathname, $callback->($entries) 821=item aio_readdir $pathname, $callback->($entries)
734 822
735Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 823Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
1100} 1188}
1101 1189
1102=item aio_rmtree $pathname, $callback->($status) 1190=item aio_rmtree $pathname, $callback->($status)
1103 1191
1104Delete a directory tree starting (and including) C<$path>, return the 1192Delete a directory tree starting (and including) C<$path>, return the
1105status of the final C<rmdir> only. This is a composite request that 1193status of the final C<rmdir> only. This is a composite request that
1106uses C<aio_scandir> to recurse into and rmdir directories, and unlink 1194uses C<aio_scandir> to recurse into and rmdir directories, and unlink
1107everything else. 1195everything else.
1108 1196
1109=cut 1197=cut
1110 1198
1230 1318
1231This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1319This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1232scalars. 1320scalars.
1233 1321
1234It touches (reads or writes) all memory pages in the specified 1322It touches (reads or writes) all memory pages in the specified
1235range inside the scalar. All caveats and parameters are the same 1323range inside the scalar. All caveats and parameters are the same
1236as for C<aio_msync>, above, except for flags, which must be either 1324as for C<aio_msync>, above, except for flags, which must be either
1237C<0> (which reads all pages and ensures they are instantiated) or 1325C<0> (which reads all pages and ensures they are instantiated) or
1238C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and 1326C<IO::AIO::MT_MODIFY>, which modifies the memory pages (by reading and
1239writing an octet from it, which dirties the page). 1327writing an octet from it, which dirties the page).
1240 1328
1241=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) 1329=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1242 1330
1243This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1331This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1277 1365
1278 aio_mlockall IO::AIO::MCL_FUTURE; 1366 aio_mlockall IO::AIO::MCL_FUTURE;
1279 1367
1280=item aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents) 1368=item aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1281 1369
1282Queries the extents of the given file (by calling the Linux FIEMAP ioctl, 1370Queries the extents of the given file (by calling the Linux C<FIEMAP>
1283see L<http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for details). If the 1371ioctl, see L<http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for details). If
1284C<ioctl> is not available on your OS, then this request will fail with 1372the ioctl is not available on your OS, then this request will fail with
1285C<ENOSYS>. 1373C<ENOSYS>.
1286 1374
1287C<$start> is the starting offset to query extents for, C<$length> is the 1375C<$start> is the starting offset to query extents for, C<$length> is the
1288size of the range to query - if it is C<undef>, then the whole file will 1376size of the range to query - if it is C<undef>, then the whole file will
1289be queried. 1377be queried.
1292C<IO::AIO::FIEMAP_FLAG_XATTR> - C<IO::AIO::FIEMAP_FLAGS_COMPAT> is also 1380C<IO::AIO::FIEMAP_FLAG_XATTR> - C<IO::AIO::FIEMAP_FLAGS_COMPAT> is also
1293exported), and is normally C<0> or C<IO::AIO::FIEMAP_FLAG_SYNC> to query 1381exported), and is normally C<0> or C<IO::AIO::FIEMAP_FLAG_SYNC> to query
1294the data portion. 1382the data portion.
1295 1383
1296C<$count> is the maximum number of extent records to return. If it is 1384C<$count> is the maximum number of extent records to return. If it is
1297C<undef>, then IO::AIO queries all extents of the file. As a very special 1385C<undef>, then IO::AIO queries all extents of the range. As a very special
1298case, if it is C<0>, then the callback receives the number of extents 1386case, if it is C<0>, then the callback receives the number of extents
1299instead of the extents themselves. 1387instead of the extents themselves (which is unreliable, see below).
1300 1388
1301If an error occurs, the callback receives no arguments. The special 1389If an error occurs, the callback receives no arguments. The special
1302C<errno> value C<IO::AIO::EBADR> is available to test for flag errors. 1390C<errno> value C<IO::AIO::EBADR> is available to test for flag errors.
1303 1391
1304Otherwise, the callback receives an array reference with extent 1392Otherwise, the callback receives an array reference with extent
1314C<IO::AIO::FIEMAP_EXTENT_DELALLOC>, C<IO::AIO::FIEMAP_EXTENT_ENCODED>, 1402C<IO::AIO::FIEMAP_EXTENT_DELALLOC>, C<IO::AIO::FIEMAP_EXTENT_ENCODED>,
1315C<IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED>, C<IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED>, 1403C<IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED>, C<IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED>,
1316C<IO::AIO::FIEMAP_EXTENT_DATA_INLINE>, C<IO::AIO::FIEMAP_EXTENT_DATA_TAIL>, 1404C<IO::AIO::FIEMAP_EXTENT_DATA_INLINE>, C<IO::AIO::FIEMAP_EXTENT_DATA_TAIL>,
1317C<IO::AIO::FIEMAP_EXTENT_UNWRITTEN>, C<IO::AIO::FIEMAP_EXTENT_MERGED> or 1405C<IO::AIO::FIEMAP_EXTENT_UNWRITTEN>, C<IO::AIO::FIEMAP_EXTENT_MERGED> or
1318C<IO::AIO::FIEMAP_EXTENT_SHARED>. 1406C<IO::AIO::FIEMAP_EXTENT_SHARED>.
1407
1408At the time of this writing (Linux 3.2), this requets is unreliable unless
1409C<$count> is C<undef>, as the kernel has all sorts of bugs preventing
1410it to return all extents of a range for files with large number of
1411extents. The code works around all these issues if C<$count> is undef.
1319 1412
1320=item aio_group $callback->(...) 1413=item aio_group $callback->(...)
1321 1414
1322This is a very special aio request: Instead of doing something, it is a 1415This is a very special aio request: Instead of doing something, it is a
1323container for other aio requests, which is useful if you want to bundle 1416container for other aio requests, which is useful if you want to bundle
1439will still point to the original directory. Most functions accepting a 1532will still point to the original directory. Most functions accepting a
1440pathname will use the directory fd on newer systems, and the string on 1533pathname will use the directory fd on newer systems, and the string on
1441older systems. Some functions (such as realpath) will always rely on the 1534older systems. Some functions (such as realpath) will always rely on the
1442string form of the pathname. 1535string form of the pathname.
1443 1536
1444So this fucntionality is mainly useful to get some protection against 1537So this functionality is mainly useful to get some protection against
1445C<chdir>, to easily get an absolute path out of a relative path for future 1538C<chdir>, to easily get an absolute path out of a relative path for future
1446reference, and to speed up doing many operations in the same directory 1539reference, and to speed up doing many operations in the same directory
1447(e.g. when stat'ing all files in a directory). 1540(e.g. when stat'ing all files in a directory).
1448 1541
1449The following functions implement this working directory abstraction: 1542The following functions implement this working directory abstraction:
1462passing C<undef> as working directory component of a pathname fails the 1555passing C<undef> as working directory component of a pathname fails the
1463request with C<ENOENT>, there is often no need for error checking in the 1556request with C<ENOENT>, there is often no need for error checking in the
1464C<aio_wd> callback, as future requests using the value will fail in the 1557C<aio_wd> callback, as future requests using the value will fail in the
1465expected way. 1558expected way.
1466 1559
1467If this call isn't available because your OS lacks it or it couldn't be
1468detected, it will be emulated by calling C<fsync> instead.
1469
1470=item IO::AIO::CWD 1560=item IO::AIO::CWD
1471 1561
1472This is a compiletime constant (object) that represents the process 1562This is a compiletime constant (object) that represents the process
1473current working directory. 1563current working directory.
1474 1564
1475Specifying this object as working directory object for a pathname is as 1565Specifying this object as working directory object for a pathname is as if
1476if the pathname would be specified directly, without a directory object, 1566the pathname would be specified directly, without a directory object. For
1477e.g., these calls are functionally identical: 1567example, these calls are functionally identical:
1478 1568
1479 aio_stat "somefile", sub { ... }; 1569 aio_stat "somefile", sub { ... };
1480 aio_stat [IO::AIO::CWD, "somefile"], sub { ... }; 1570 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1481 1571
1482=back 1572=back
1483 1573
1574To recover the path associated with an IO::AIO::WD object, you can use
1575C<aio_realpath>:
1576
1577 aio_realpath $wd, sub {
1578 warn "path is $_[0]\n";
1579 };
1580
1581Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
1582sometimes, fall back to using an absolue path.
1484 1583
1485=head2 IO::AIO::REQ CLASS 1584=head2 IO::AIO::REQ CLASS
1486 1585
1487All non-aggregate C<aio_*> functions return an object of this class when 1586All non-aggregate C<aio_*> functions return an object of this class when
1488called in non-void context. 1587called in non-void context.
1666 1765
1667See C<poll_cb> for an example. 1766See C<poll_cb> for an example.
1668 1767
1669=item IO::AIO::poll_cb 1768=item IO::AIO::poll_cb
1670 1769
1671Process some outstanding events on the result pipe. You have to call 1770Process some requests that have reached the result phase (i.e. they have
1771been executed but the results are not yet reported). You have to call
1772this "regularly" to finish outstanding requests.
1773
1672this regularly. Returns C<0> if all events could be processed (or there 1774Returns C<0> if all events could be processed (or there were no
1673were no events to process), or C<-1> if it returned earlier for whatever 1775events to process), or C<-1> if it returned earlier for whatever
1674reason. Returns immediately when no events are outstanding. The amount of 1776reason. Returns immediately when no events are outstanding. The amount
1675events processed depends on the settings of C<IO::AIO::max_poll_req> and 1777of events processed depends on the settings of C<IO::AIO::max_poll_req>,
1676C<IO::AIO::max_poll_time>. 1778C<IO::AIO::max_poll_time> and C<IO::AIO::max_outstanding>.
1677 1779
1678If not all requests were processed for whatever reason, the filehandle 1780If not all requests were processed for whatever reason, the poll file
1679will still be ready when C<poll_cb> returns, so normally you don't have to 1781descriptor will still be ready when C<poll_cb> returns, so normally you
1680do anything special to have it called later. 1782don't have to do anything special to have it called later.
1681 1783
1682Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes 1784Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
1683ready, it can be beneficial to call this function from loops which submit 1785ready, it can be beneficial to call this function from loops which submit
1684a lot of requests, to make sure the results get processed when they become 1786a lot of requests, to make sure the results get processed when they become
1685available and not just when the loop is finished and the event loop takes 1787available and not just when the loop is finished and the event loop takes
1694 poll => 'r', async => 1, 1796 poll => 'r', async => 1,
1695 cb => \&IO::AIO::poll_cb); 1797 cb => \&IO::AIO::poll_cb);
1696 1798
1697=item IO::AIO::poll_wait 1799=item IO::AIO::poll_wait
1698 1800
1699If there are any outstanding requests and none of them in the result 1801Wait until either at least one request is in the result phase or no
1700phase, wait till the result filehandle becomes ready for reading (simply 1802requests are outstanding anymore.
1701does a C<select> on the filehandle. This is useful if you want to 1803
1702synchronously wait for some requests to finish). 1804This is useful if you want to synchronously wait for some requests to
1805become ready, without actually handling them.
1703 1806
1704See C<nreqs> for an example. 1807See C<nreqs> for an example.
1705 1808
1706=item IO::AIO::poll 1809=item IO::AIO::poll
1707 1810
1828 1931
1829This is a very bad function to use in interactive programs because it 1932This is a very bad function to use in interactive programs because it
1830blocks, and a bad way to reduce concurrency because it is inexact: Better 1933blocks, and a bad way to reduce concurrency because it is inexact: Better
1831use an C<aio_group> together with a feed callback. 1934use an C<aio_group> together with a feed callback.
1832 1935
1833It's main use is in scripts without an event loop - when you want to stat 1936Its main use is in scripts without an event loop - when you want to stat
1834a lot of files, you can write somehting like this: 1937a lot of files, you can write somehting like this:
1835 1938
1836 IO::AIO::max_outstanding 32; 1939 IO::AIO::max_outstanding 32;
1837 1940
1838 for my $path (...) { 1941 for my $path (...) {
1878 1981
1879=back 1982=back
1880 1983
1881=head3 MISCELLANEOUS FUNCTIONS 1984=head3 MISCELLANEOUS FUNCTIONS
1882 1985
1883IO::AIO implements some functions that might be useful, but are not 1986IO::AIO implements some functions that are useful when you want to use
1884asynchronous. 1987some "Advanced I/O" function not available to in Perl, without going the
1988"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
1989counterpart.
1885 1990
1886=over 4 1991=over 4
1887 1992
1888=item IO::AIO::sendfile $ofh, $ifh, $offset, $count 1993=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1889 1994
2007 2112
2008See the C<splice(2)> manpage for details. 2113See the C<splice(2)> manpage for details.
2009 2114
2010=item IO::AIO::tee $r_fh, $w_fh, $length, $flags 2115=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2011 2116
2012Calls the GNU/Linux C<tee(2)> syscall, see it's manpage and the 2117Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
2013description for C<IO::AIO::splice> above for details. 2118description for C<IO::AIO::splice> above for details.
2119
2120=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2121
2122Attempts to query or change the pipe buffer size. Obviously works only
2123on pipes, and currently works only on GNU/Linux systems, and fails with
2124C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2125size on other systems, drop me a note.
2014 2126
2015=back 2127=back
2016 2128
2017=cut 2129=cut
2018 2130

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines