--- IO-AIO/AIO.pm 2012/10/11 05:01:56 1.238 +++ IO-AIO/AIO.pm 2015/02/11 19:32:36 1.251 @@ -70,7 +70,6 @@ This is a simple example that uses the EV module and loads F asynchronously: - use Fcntl; use EV; use IO::AIO; @@ -170,7 +169,7 @@ use base 'Exporter'; BEGIN { - our $VERSION = '4.18'; + our $VERSION = 4.32; our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx @@ -230,7 +229,7 @@ aio_link $srcpath, $dstpath, $callback->($status) aio_symlink $srcpath, $dstpath, $callback->($status) aio_readlink $pathname, $callback->($link) - aio_realpath $pathname, $callback->($link) + aio_realpath $pathname, $callback->($path) aio_rename $srcpath, $dstpath, $callback->($status) aio_mkdir $pathname, $mode, $callback->($status) aio_rmdir $pathname, $callback->($status) @@ -605,8 +604,8 @@ fsid => 1810 } -Here is a (likely partial) list of fsid values used by Linux - it is safe -to hardcode these when the $^O is C: +Here is a (likely partial - send me updates!) list of fsid values used by +Linux - it is safe to hardcode these when C<$^O> is C: 0x0000adf5 adfs 0x0000adff affs @@ -725,8 +724,8 @@ =item aio_allocate $fh, $mode, $offset, $len, $callback->($status) -Allocates or freed disk space according to the C<$mode> argument. See the -linux C docuemntation for details. +Allocates or frees disk space according to the C<$mode> argument. See the +linux C documentation for details. C<$mode> can currently be C<0> or C to allocate space, or C($path) Asynchronously make the path absolute and resolve any symlinks in -C<$path>. The resulting path only consists of directories (Same as +C<$path>. The resulting path only consists of directories (same as L). This request can be used to get the absolute path of the current working @@ -797,6 +796,10 @@ Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as rename(2) and call the callback with the result code. +On systems that support the AIO::WD working directory abstraction +natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead +of failing, C is called on the absolute path of C<$wd>. + =item aio_mkdir $pathname, $mode, $callback->($status) @@ -810,6 +813,10 @@ Asynchronously rmdir (delete) a directory and call the callback with the result code. +On systems that support the AIO::WD working directory abstraction +natively, the case C<[$wd, "."]> is specialcased - instead of failing, +C is called on the absolute path of C<$wd>. + =item aio_readdir $pathname, $callback->($entries) @@ -1183,7 +1190,7 @@ =item aio_rmtree $pathname, $callback->($status) Delete a directory tree starting (and including) C<$path>, return the -status of the final C only. This is a composite request that +status of the final C only. This is a composite request that uses C to recurse into and rmdir directories, and unlink everything else. @@ -1313,10 +1320,10 @@ scalars. It touches (reads or writes) all memory pages in the specified -range inside the scalar. All caveats and parameters are the same +range inside the scalar. All caveats and parameters are the same as for C, above, except for flags, which must be either C<0> (which reads all pages and ensures they are instantiated) or -C, which modifies the memory page s(by reading and +C, which modifies the memory pages (by reading and writing an octet from it, which dirties the page). =item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) @@ -1495,9 +1502,9 @@ }; }; -That C is a request and not a normal function shows that creating -an IO::AIO::WD object is itself a potentially blocking operation, which is -why it is done asynchronously. +The fact that C is a request and not a normal function shows that +creating an IO::AIO::WD object is itself a potentially blocking operation, +which is why it is done asynchronously. To stat the directory obtained with C above, one could write either of the following three request calls: @@ -1527,7 +1534,7 @@ older systems. Some functions (such as realpath) will always rely on the string form of the pathname. -So this fucntionality is mainly useful to get some protection against +So this functionality is mainly useful to get some protection against C, to easily get an absolute path out of a relative path for future reference, and to speed up doing many operations in the same directory (e.g. when stat'ing all files in a directory). @@ -1550,23 +1557,29 @@ C callback, as future requests using the value will fail in the expected way. -If this call isn't available because your OS lacks it or it couldn't be -detected, it will be emulated by calling C instead. - =item IO::AIO::CWD This is a compiletime constant (object) that represents the process current working directory. -Specifying this object as working directory object for a pathname is as -if the pathname would be specified directly, without a directory object, -e.g., these calls are functionally identical: +Specifying this object as working directory object for a pathname is as if +the pathname would be specified directly, without a directory object. For +example, these calls are functionally identical: aio_stat "somefile", sub { ... }; aio_stat [IO::AIO::CWD, "somefile"], sub { ... }; =back +To recover the path associated with an IO::AIO::WD object, you can use +C: + + aio_realpath $wd, sub { + warn "path is $_[0]\n"; + }; + +Currently, C always, and C and C +sometimes, fall back to using an absolue path. =head2 IO::AIO::REQ CLASS @@ -1754,16 +1767,19 @@ =item IO::AIO::poll_cb -Process some outstanding events on the result pipe. You have to call -this regularly. Returns C<0> if all events could be processed (or there -were no events to process), or C<-1> if it returned earlier for whatever -reason. Returns immediately when no events are outstanding. The amount of -events processed depends on the settings of C and -C. - -If not all requests were processed for whatever reason, the filehandle -will still be ready when C returns, so normally you don't have to -do anything special to have it called later. +Process some requests that have reached the result phase (i.e. they have +been executed but the results are not yet reported). You have to call +this "regularly" to finish outstanding requests. + +Returns C<0> if all events could be processed (or there were no +events to process), or C<-1> if it returned earlier for whatever +reason. Returns immediately when no events are outstanding. The amount +of events processed depends on the settings of C, +C and C. + +If not all requests were processed for whatever reason, the poll file +descriptor will still be ready when C returns, so normally you +don't have to do anything special to have it called later. Apart from calling C when the event filehandle becomes ready, it can be beneficial to call this function from loops which submit @@ -1782,10 +1798,11 @@ =item IO::AIO::poll_wait -If there are any outstanding requests and none of them in the result -phase, wait till the result filehandle becomes ready for reading (simply -does a C