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.210 by root, Tue Sep 27 01:43:03 2011 UTC vs.
Revision 1.212 by root, Thu Sep 29 22:42:15 2011 UTC

… …
281=head2 AIO REQUEST FUNCTIONS 281=head2 AIO REQUEST FUNCTIONS
282 282
283All the C<aio_*> calls are more or less thin wrappers around the syscall 283All the C<aio_*> calls are more or less thin wrappers around the syscall
284with the same name (sans C<aio_>). The arguments are similar or identical, 284with the same name (sans C<aio_>). The arguments are similar or identical,
285and they all accept an additional (and optional) C<$callback> argument 285and they all accept an additional (and optional) C<$callback> argument
286which must be a code reference. This code reference will get called with 286which must be a code reference. This code reference will be called after
287the syscall return code (e.g. most syscalls return C<-1> on error, unlike 287the syscall has been executed in an asynchronous fashion. The results
288perl, which usually delivers "false") as its sole argument after the given 288of the request will be passed as arguments to the callback (and, if an
289syscall has been executed asynchronously. 289error occured, in C<$!>) - for most requests the syscall return code (e.g.
290most syscalls return C<-1> on error, unlike perl, which usually delivers
291"false").
292
293Some requests (such as C<aio_readdir>) pass the actual results and
294communicate failures by passing C<undef>.
290 295
291All functions expecting a filehandle keep a copy of the filehandle 296All functions expecting a filehandle keep a copy of the filehandle
292internally until the request has finished. 297internally until the request has finished.
293 298
294All functions return request objects of type L<IO::AIO::REQ> that allow 299All functions return request objects of type L<IO::AIO::REQ> that allow
295further manipulation of those requests while they are in-flight. 300further manipulation of those requests while they are in-flight.
296 301
297The pathnames you pass to these routines I<should> be absolute. The 302The pathnames you pass to these routines I<should> be absolute. The
298reason for this is that at the time the request is being executed, the 303reason for this is that at the time the request is being executed, the
299current working directory could have changed. Alternatively, you can make 304current working directory could have changed. Alternatively, you can
300sure that you never change the current working directory anywhere in 305make sure that you never change the current working directory anywhere
301the program and then use relative paths. Lastly, you can take advantage 306in the program and then use relative paths. You can also take advantage
302of IO::AIOs working directory abstraction - see the description of the 307of IO::AIOs working directory abstraction, that lets you specify paths
308relative to some previously-opened "working directory object" - see the
303C<IO::AIO::WD> class later in this document. 309description of the C<IO::AIO::WD> class later in this document.
304 310
305To encode pathnames as octets, either make sure you either: a) always pass 311To encode pathnames as octets, either make sure you either: a) always pass
306in filenames you got from outside (command line, readdir etc.) without 312in filenames you got from outside (command line, readdir etc.) without
307tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode 313tinkering, b) are in your native filesystem encoding, c) use the Encode
308your pathnames to the locale (or other) encoding in effect in the user 314module and encode your pathnames to the locale (or other) encoding in
309environment, d) use Glib::filename_from_unicode on unicode filenames or e) 315effect in the user environment, d) use Glib::filename_from_unicode on
310use something else to ensure your scalar has the correct contents. 316unicode filenames or e) use something else to ensure your scalar has the
317correct contents.
311 318
312This works, btw. independent of the internal UTF-8 bit, which IO::AIO 319This works, btw. independent of the internal UTF-8 bit, which IO::AIO
313handles correctly whether it is set or not. 320handles correctly whether it is set or not.
314 321
315=over 4 322=over 4
… …
967 my $grp = aio_group $cb; 974 my $grp = aio_group $cb;
968 975
969 $maxreq = 4 if $maxreq <= 0; 976 $maxreq = 4 if $maxreq <= 0;
970 977
971 # get a wd object 978 # get a wd object
972
973 aioreq_pri $pri; 979 aioreq_pri $pri;
974 add $grp aio_wd $path, sub { 980 add $grp aio_wd $path, sub {
981 $_[0]
982 or return $grp->result ();
983
975 my $wd = [shift, "."]; 984 my $wd = [shift, "."];
976 985
977 # stat once 986 # stat once
978 aioreq_pri $pri; 987 aioreq_pri $pri;
979 add $grp aio_stat $wd, sub { 988 add $grp aio_stat $wd, sub {
… …
1505 1514
1506Sets a feeder/generator on this group: every group can have an attached 1515Sets a feeder/generator on this group: every group can have an attached
1507generator that generates requests if idle. The idea behind this is that, 1516generator that generates requests if idle. The idea behind this is that,
1508although you could just queue as many requests as you want in a group, 1517although you could just queue as many requests as you want in a group,
1509this might starve other requests for a potentially long time. For example, 1518this might starve other requests for a potentially long time. For example,
1510C<aio_scandir> might generate hundreds of thousands C<aio_stat> requests, 1519C<aio_scandir> might generate hundreds of thousands of C<aio_stat>
1511delaying any later requests for a long time. 1520requests, delaying any later requests for a long time.
1512 1521
1513To avoid this, and allow incremental generation of requests, you can 1522To avoid this, and allow incremental generation of requests, you can
1514instead a group and set a feeder on it that generates those requests. The 1523instead a group and set a feeder on it that generates those requests. The
1515feed callback will be called whenever there are few enough (see C<limit>, 1524feed callback will be called whenever there are few enough (see C<limit>,
1516below) requests active in the group itself and is expected to queue more 1525below) requests active in the group itself and is expected to queue more

Diff Legend

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