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.236 by root, Fri Aug 24 15:33:06 2012 UTC vs.
Revision 1.241 by root, Fri Dec 28 07:33:41 2012 UTC

… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '4.16'; 173 our $VERSION = '4.18';
174 174
175 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close 175 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 176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync 177 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
178 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_allocate 178 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_allocate
… …
783 783
784 784
785=item aio_realpath $pathname, $callback->($path) 785=item aio_realpath $pathname, $callback->($path)
786 786
787Asynchronously make the path absolute and resolve any symlinks in 787Asynchronously make the path absolute and resolve any symlinks in
788C<$path>. The resulting path only consists of directories (Same as 788C<$path>. The resulting path only consists of directories (same as
789L<Cwd::realpath>). 789L<Cwd::realpath>).
790 790
791This request can be used to get the absolute path of the current working 791This request can be used to get the absolute path of the current working
792directory by passing it a path of F<.> (a single dot). 792directory by passing it a path of F<.> (a single dot).
793 793
794 794
795=item aio_rename $srcpath, $dstpath, $callback->($status) 795=item aio_rename $srcpath, $dstpath, $callback->($status)
796 796
797Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 797Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
798rename(2) and call the callback with the result code. 798rename(2) and call the callback with the result code.
799
800On systems that support the AIO::WD working directory abstraction
801natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
802of failing, C<rename> is called on the absolute path of C<$wd>.
799 803
800 804
801=item aio_mkdir $pathname, $mode, $callback->($status) 805=item aio_mkdir $pathname, $mode, $callback->($status)
802 806
803Asynchronously mkdir (create) a directory and call the callback with 807Asynchronously mkdir (create) a directory and call the callback with
… …
807 811
808=item aio_rmdir $pathname, $callback->($status) 812=item aio_rmdir $pathname, $callback->($status)
809 813
810Asynchronously rmdir (delete) a directory and call the callback with the 814Asynchronously rmdir (delete) a directory and call the callback with the
811result code. 815result code.
816
817On systems that support the AIO::WD working directory abstraction
818natively, the case C<[$wd, "."]> is specialcased - instead of failing,
819C<rmdir> is called on the absolute path of C<$wd>.
812 820
813 821
814=item aio_readdir $pathname, $callback->($entries) 822=item aio_readdir $pathname, $callback->($entries)
815 823
816Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 824Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
… …
1181} 1189}
1182 1190
1183=item aio_rmtree $pathname, $callback->($status) 1191=item aio_rmtree $pathname, $callback->($status)
1184 1192
1185Delete a directory tree starting (and including) C<$path>, return the 1193Delete a directory tree starting (and including) C<$path>, return the
1186status of the final C<rmdir> only. This is a composite request that 1194status of the final C<rmdir> only. This is a composite request that
1187uses C<aio_scandir> to recurse into and rmdir directories, and unlink 1195uses C<aio_scandir> to recurse into and rmdir directories, and unlink
1188everything else. 1196everything else.
1189 1197
1190=cut 1198=cut
1191 1199
… …
1311 1319
1312This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1320This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1313scalars. 1321scalars.
1314 1322
1315It touches (reads or writes) all memory pages in the specified 1323It touches (reads or writes) all memory pages in the specified
1316range inside the scalar. All caveats and parameters are the same 1324range inside the scalar. All caveats and parameters are the same
1317as for C<aio_msync>, above, except for flags, which must be either 1325as for C<aio_msync>, above, except for flags, which must be either
1318C<0> (which reads all pages and ensures they are instantiated) or 1326C<0> (which reads all pages and ensures they are instantiated) or
1319C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and 1327C<IO::AIO::MT_MODIFY>, which modifies the memory pages (by reading and
1320writing an octet from it, which dirties the page). 1328writing an octet from it, which dirties the page).
1321 1329
1322=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) 1330=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1323 1331
1324This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1332This is a rather advanced IO::AIO call, which works best on mmap(2)ed
… …
1525will still point to the original directory. Most functions accepting a 1533will still point to the original directory. Most functions accepting a
1526pathname will use the directory fd on newer systems, and the string on 1534pathname will use the directory fd on newer systems, and the string on
1527older systems. Some functions (such as realpath) will always rely on the 1535older systems. Some functions (such as realpath) will always rely on the
1528string form of the pathname. 1536string form of the pathname.
1529 1537
1530So this fucntionality is mainly useful to get some protection against 1538So this functionality is mainly useful to get some protection against
1531C<chdir>, to easily get an absolute path out of a relative path for future 1539C<chdir>, to easily get an absolute path out of a relative path for future
1532reference, and to speed up doing many operations in the same directory 1540reference, and to speed up doing many operations in the same directory
1533(e.g. when stat'ing all files in a directory). 1541(e.g. when stat'ing all files in a directory).
1534 1542
1535The following functions implement this working directory abstraction: 1543The following functions implement this working directory abstraction:
… …
1556=item IO::AIO::CWD 1564=item IO::AIO::CWD
1557 1565
1558This is a compiletime constant (object) that represents the process 1566This is a compiletime constant (object) that represents the process
1559current working directory. 1567current working directory.
1560 1568
1561Specifying this object as working directory object for a pathname is as 1569Specifying this object as working directory object for a pathname is as if
1562if the pathname would be specified directly, without a directory object, 1570the pathname would be specified directly, without a directory object. For
1563e.g., these calls are functionally identical: 1571example, these calls are functionally identical:
1564 1572
1565 aio_stat "somefile", sub { ... }; 1573 aio_stat "somefile", sub { ... };
1566 aio_stat [IO::AIO::CWD, "somefile"], sub { ... }; 1574 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1567 1575
1568=back 1576=back
1569 1577
1578To recover the path associated with an IO::AIO::WD object, you can use
1579C<aio_realpath>:
1580
1581 aio_realpath $wd, sub {
1582 warn "path is $_[0]\n";
1583 };
1584
1585Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
1586sometimes, fall back to using an absolue path.
1570 1587
1571=head2 IO::AIO::REQ CLASS 1588=head2 IO::AIO::REQ CLASS
1572 1589
1573All non-aggregate C<aio_*> functions return an object of this class when 1590All non-aggregate C<aio_*> functions return an object of this class when
1574called in non-void context. 1591called in non-void context.
… …
1752 1769
1753See C<poll_cb> for an example. 1770See C<poll_cb> for an example.
1754 1771
1755=item IO::AIO::poll_cb 1772=item IO::AIO::poll_cb
1756 1773
1757Process some outstanding events on the result pipe. You have to call 1774Process some requests that have reached the result phase (i.e. they have
1775been executed but the results are not yet reported). You have to call
1776this "regularly" to finish outstanding requests.
1777
1758this regularly. Returns C<0> if all events could be processed (or there 1778Returns C<0> if all events could be processed (or there were no
1759were no events to process), or C<-1> if it returned earlier for whatever 1779events to process), or C<-1> if it returned earlier for whatever
1760reason. Returns immediately when no events are outstanding. The amount of 1780reason. Returns immediately when no events are outstanding. The amount
1761events processed depends on the settings of C<IO::AIO::max_poll_req> and 1781of events processed depends on the settings of C<IO::AIO::max_poll_req>,
1762C<IO::AIO::max_poll_time>. 1782C<IO::AIO::max_poll_time> and C<IO::AIO::max_outstanding>.
1763 1783
1764If not all requests were processed for whatever reason, the filehandle 1784If not all requests were processed for whatever reason, the poll file
1765will still be ready when C<poll_cb> returns, so normally you don't have to 1785descriptor will still be ready when C<poll_cb> returns, so normally you
1766do anything special to have it called later. 1786don't have to do anything special to have it called later.
1767 1787
1768Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes 1788Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
1769ready, it can be beneficial to call this function from loops which submit 1789ready, it can be beneficial to call this function from loops which submit
1770a lot of requests, to make sure the results get processed when they become 1790a lot of requests, to make sure the results get processed when they become
1771available and not just when the loop is finished and the event loop takes 1791available and not just when the loop is finished and the event loop takes
… …
1780 poll => 'r', async => 1, 1800 poll => 'r', async => 1,
1781 cb => \&IO::AIO::poll_cb); 1801 cb => \&IO::AIO::poll_cb);
1782 1802
1783=item IO::AIO::poll_wait 1803=item IO::AIO::poll_wait
1784 1804
1785If there are any outstanding requests and none of them in the result 1805Wait until either at least one request is in the result phase or no
1786phase, wait till the result filehandle becomes ready for reading (simply 1806requests are outstanding anymore.
1787does a C<select> on the filehandle. This is useful if you want to 1807
1788synchronously wait for some requests to finish). 1808This is useful if you want to synchronously wait for some requests to
1809become ready, without actually handling them.
1789 1810
1790See C<nreqs> for an example. 1811See C<nreqs> for an example.
1791 1812
1792=item IO::AIO::poll 1813=item IO::AIO::poll
1793 1814

Diff Legend

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