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.59 by root, Sun Oct 22 10:33:26 2006 UTC vs.
Revision 1.94 by root, Wed Nov 8 02:01:02 2006 UTC

… …
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use IO::AIO; 7 use IO::AIO;
8 8
9 aio_open "/etc/passwd", O_RDONLY, 0, sub { 9 aio_open "/etc/passwd", O_RDONLY, 0, sub {
10 my ($fh) = @_; 10 my $fh = shift
11 or die "/etc/passwd: $!";
11 ... 12 ...
12 }; 13 };
13 14
14 aio_unlink "/tmp/file", sub { }; 15 aio_unlink "/tmp/file", sub { };
15 16
… …
18 }; 19 };
19 20
20 # version 2+ has request and group objects 21 # version 2+ has request and group objects
21 use IO::AIO 2; 22 use IO::AIO 2;
22 23
24 aioreq_pri 4; # give next request a very high priority
23 my $req = aio_unlink "/tmp/file", sub { }; 25 my $req = aio_unlink "/tmp/file", sub { };
24 $req->cancel; # cancel request if still in queue 26 $req->cancel; # cancel request if still in queue
25 27
26 my $grp = aio_group sub { print "all stats done\n" }; 28 my $grp = aio_group sub { print "all stats done\n" };
27 add $grp aio_stat "..." for ...; 29 add $grp aio_stat "..." for ...;
… …
50=head1 DESCRIPTION 52=head1 DESCRIPTION
51 53
52This module implements asynchronous I/O using whatever means your 54This module implements asynchronous I/O using whatever means your
53operating system supports. 55operating system supports.
54 56
57Asynchronous means that operations that can normally block your program
58(e.g. reading from disk) will be done asynchronously: the operation
59will still block, but you can do something else in the meantime. This
60is extremely useful for programs that need to stay interactive even
61when doing heavy I/O (GUI programs, high performance network servers
62etc.), but can also be used to easily do operations in parallel that are
63normally done sequentially, e.g. stat'ing many files, which is much faster
64on a RAID volume or over NFS when you do a number of stat operations
65concurrently.
66
67While most of this works on all types of file descriptors (for example
68sockets), using these functions on file descriptors that support
69nonblocking operation (again, sockets, pipes etc.) is very inefficient or
70might not work (aio_read fails on sockets/pipes/fifos). Use an event loop
71for that (such as the L<Event|Event> module): IO::AIO will naturally fit
72into such an event loop itself.
73
55Currently, a number of threads are started that execute your read/writes 74In this version, a number of threads are started that execute your
56and signal their completion. You don't need thread support in your libc or 75requests and signal their completion. You don't need thread support
57perl, and the threads created by this module will not be visible to the 76in perl, and the threads created by this module will not be visible
58pthreads library. In the future, this module might make use of the native 77to perl. In the future, this module might make use of the native aio
59aio functions available on many operating systems. However, they are often 78functions available on many operating systems. However, they are often
60not well-supported (Linux doesn't allow them on normal files currently, 79not well-supported or restricted (GNU/Linux doesn't allow them on normal
61for example), and they would only support aio_read and aio_write, so the 80files currently, for example), and they would only support aio_read and
62remaining functionality would have to be implemented using threads anyway. 81aio_write, so the remaining functionality would have to be implemented
82using threads anyway.
63 83
64Although the module will work with in the presence of other threads, it is 84Although the module will work with in the presence of other (Perl-)
65currently not reentrant, so use appropriate locking yourself, always call 85threads, it is currently not reentrant in any way, so use appropriate
66C<poll_cb> from within the same thread, or never call C<poll_cb> (or other 86locking yourself, always call C<poll_cb> from within the same thread, or
67C<aio_> functions) recursively. 87never call C<poll_cb> (or other C<aio_> functions) recursively.
88
89=head2 EXAMPLE
90
91This is a simple example that uses the Event module and loads
92F</etc/passwd> asynchronously:
93
94 use Fcntl;
95 use Event;
96 use IO::AIO;
97
98 # register the IO::AIO callback with Event
99 Event->io (fd => IO::AIO::poll_fileno,
100 poll => 'r',
101 cb => \&IO::AIO::poll_cb);
102
103 # queue the request to open /etc/passwd
104 aio_open "/etc/passwd", O_RDONLY, 0, sub {
105 my $fh = shift
106 or die "error while opening: $!";
107
108 # stat'ing filehandles is generally non-blocking
109 my $size = -s $fh;
110
111 # queue a request to read the file
112 my $contents;
113 aio_read $fh, 0, $size, $contents, 0, sub {
114 $_[0] == $size
115 or die "short read: $!";
116
117 close $fh;
118
119 # file contents now in $contents
120 print $contents;
121
122 # exit event loop and program
123 Event::unloop;
124 };
125 };
126
127 # possibly queue up other requests, or open GUI windows,
128 # check for sockets etc. etc.
129
130 # process events as long as there are some:
131 Event::loop;
132
133=head1 REQUEST ANATOMY AND LIFETIME
134
135Every C<aio_*> function creates a request. which is a C data structure not
136directly visible to Perl.
137
138If called in non-void context, every request function returns a Perl
139object representing the request. In void context, nothing is returned,
140which saves a bit of memory.
141
142The perl object is a fairly standard ref-to-hash object. The hash contents
143are not used by IO::AIO so you are free to store anything you like in it.
144
145During their existance, aio requests travel through the following states,
146in order:
147
148=over 4
149
150=item ready
151
152Immediately after a request is created it is put into the ready state,
153waiting for a thread to execute it.
154
155=item execute
156
157A thread has accepted the request for processing and is currently
158executing it (e.g. blocking in read).
159
160=item pending
161
162The request has been executed and is waiting for result processing.
163
164While request submission and execution is fully asynchronous, result
165processing is not and relies on the perl interpreter calling C<poll_cb>
166(or another function with the same effect).
167
168=item result
169
170The request results are processed synchronously by C<poll_cb>.
171
172The C<poll_cb> function will process all outstanding aio requests by
173calling their callbacks, freeing memory associated with them and managing
174any groups they are contained in.
175
176=item done
177
178Request has reached the end of its lifetime and holds no resources anymore
179(except possibly for the Perl object, but its connection to the actual
180aio request is severed and calling its methods will either do nothing or
181result in a runtime error).
182
183=back
68 184
69=cut 185=cut
70 186
71package IO::AIO; 187package IO::AIO;
72 188
… …
74use strict 'vars'; 190use strict 'vars';
75 191
76use base 'Exporter'; 192use base 'Exporter';
77 193
78BEGIN { 194BEGIN {
79 our $VERSION = '2.0'; 195 our $VERSION = '2.2';
80 196
81 our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat 197 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
82 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink 198 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
83 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move 199 aio_readlink aio_fsync aio_fdatasync aio_readahead aio_rename aio_link
84 aio_group); 200 aio_move aio_copy aio_group aio_nop aio_mknod);
85 our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 201 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
202 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
203 min_parallel max_parallel max_idle
204 nreqs nready npending nthreads
205 max_poll_time max_poll_reqs);
86 206
87 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 207 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
88 208
89 require XSLoader; 209 require XSLoader;
90 XSLoader::load ("IO::AIO", $VERSION); 210 XSLoader::load ("IO::AIO", $VERSION);
91} 211}
92 212
93=head1 FUNCTIONS 213=head1 FUNCTIONS
94 214
95=head2 AIO FUNCTIONS 215=head2 AIO REQUEST FUNCTIONS
96 216
97All the C<aio_*> calls are more or less thin wrappers around the syscall 217All the C<aio_*> calls are more or less thin wrappers around the syscall
98with the same name (sans C<aio_>). The arguments are similar or identical, 218with the same name (sans C<aio_>). The arguments are similar or identical,
99and they all accept an additional (and optional) C<$callback> argument 219and they all accept an additional (and optional) C<$callback> argument
100which must be a code reference. This code reference will get called with 220which must be a code reference. This code reference will get called with
… …
103syscall has been executed asynchronously. 223syscall has been executed asynchronously.
104 224
105All functions expecting a filehandle keep a copy of the filehandle 225All functions expecting a filehandle keep a copy of the filehandle
106internally until the request has finished. 226internally until the request has finished.
107 227
108All requests return objects of type L<IO::AIO::REQ> that allow further 228All functions return request objects of type L<IO::AIO::REQ> that allow
109manipulation of those requests while they are in-flight. 229further manipulation of those requests while they are in-flight.
110 230
111The pathnames you pass to these routines I<must> be absolute and 231The pathnames you pass to these routines I<must> be absolute and
112encoded in byte form. The reason for the former is that at the time the 232encoded as octets. The reason for the former is that at the time the
113request is being executed, the current working directory could have 233request is being executed, the current working directory could have
114changed. Alternatively, you can make sure that you never change the 234changed. Alternatively, you can make sure that you never change the
115current working directory. 235current working directory anywhere in the program and then use relative
236paths.
116 237
117To encode pathnames to byte form, either make sure you either: a) 238To encode pathnames as octets, either make sure you either: a) always pass
118always pass in filenames you got from outside (command line, readdir 239in filenames you got from outside (command line, readdir etc.) without
119etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and encode 240tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode
120your pathnames to the locale (or other) encoding in effect in the user 241your pathnames to the locale (or other) encoding in effect in the user
121environment, d) use Glib::filename_from_unicode on unicode filenames or e) 242environment, d) use Glib::filename_from_unicode on unicode filenames or e)
122use something else. 243use something else to ensure your scalar has the correct contents.
244
245This works, btw. independent of the internal UTF-8 bit, which IO::AIO
246handles correctly wether it is set or not.
123 247
124=over 4 248=over 4
249
250=item $prev_pri = aioreq_pri [$pri]
251
252Returns the priority value that would be used for the next request and, if
253C<$pri> is given, sets the priority for the next aio request.
254
255The default priority is C<0>, the minimum and maximum priorities are C<-4>
256and C<4>, respectively. Requests with higher priority will be serviced
257first.
258
259The priority will be reset to C<0> after each call to one of the C<aio_*>
260functions.
261
262Example: open a file with low priority, then read something from it with
263higher priority so the read request is serviced before other low priority
264open requests (potentially spamming the cache):
265
266 aioreq_pri -3;
267 aio_open ..., sub {
268 return unless $_[0];
269
270 aioreq_pri -2;
271 aio_read $_[0], ..., sub {
272 ...
273 };
274 };
275
276=item aioreq_nice $pri_adjust
277
278Similar to C<aioreq_pri>, but subtracts the given value from the current
279priority, so the effect is cumulative.
125 280
126=item aio_open $pathname, $flags, $mode, $callback->($fh) 281=item aio_open $pathname, $flags, $mode, $callback->($fh)
127 282
128Asynchronously open or create a file and call the callback with a newly 283Asynchronously open or create a file and call the callback with a newly
129created filehandle for the file. 284created filehandle for the file.
… …
179 334
180 aio_read $fh, 7, 15, $buffer, 0, sub { 335 aio_read $fh, 7, 15, $buffer, 0, sub {
181 $_[0] > 0 or die "read error: $!"; 336 $_[0] > 0 or die "read error: $!";
182 print "read $_[0] bytes: <$buffer>\n"; 337 print "read $_[0] bytes: <$buffer>\n";
183 }; 338 };
184
185=item aio_move $srcpath, $dstpath, $callback->($status)
186
187[EXPERIMENTAL due to internal aio_group use]
188
189Try to move the I<file> (directories not supported as either source or
190destination) from C<$srcpath> to C<$dstpath> and call the callback with
191the C<0> (error) or C<-1> ok.
192
193This is a composite request that tries to rename(2) the file first. If
194rename files with C<EXDEV>, it creates the destination file with mode 0200
195and copies the contents of the source file into it using C<aio_sendfile>,
196followed by restoring atime, mtime, access mode and uid/gid, in that
197order, and unlinking the C<$srcpath>.
198
199If an error occurs, the partial destination file will be unlinked, if
200possible, except when setting atime, mtime, access mode and uid/gid, where
201errors are being ignored.
202
203=cut
204
205sub aio_move($$$) {
206 my ($src, $dst, $cb) = @_;
207
208 my $grp = aio_group $cb;
209
210 add $grp aio_rename $src, $dst, sub {
211 if ($_[0] && $! == EXDEV) {
212 add $grp aio_open $src, O_RDONLY, 0, sub {
213 if (my $src_fh = $_[0]) {
214 my @stat = stat $src_fh;
215
216 add $grp aio_open $dst, O_WRONLY, 0200, sub {
217 if (my $dst_fh = $_[0]) {
218 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
219 close $src_fh;
220
221 if ($_[0] == $stat[7]) {
222 utime $stat[8], $stat[9], $dst;
223 chmod $stat[2] & 07777, $dst_fh;
224 chown $stat[4], $stat[5], $dst_fh;
225 close $dst_fh;
226
227 add $grp aio_unlink $src, sub {
228 $grp->result ($_[0]);
229 };
230 } else {
231 my $errno = $!;
232 add $grp aio_unlink $dst, sub {
233 $! = $errno;
234 $grp->result (-1);
235 };
236 }
237 };
238 } else {
239 $grp->result (-1);
240 }
241 },
242
243 } else {
244 $grp->result (-1);
245 }
246 };
247 } else {
248 $grp->result ($_[0]);
249 }
250 };
251
252 $grp
253}
254 339
255=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 340=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
256 341
257Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts 342Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
258reading at byte offset C<$in_offset>, and starts writing at the current 343reading at byte offset C<$in_offset>, and starts writing at the current
… …
314=item aio_unlink $pathname, $callback->($status) 399=item aio_unlink $pathname, $callback->($status)
315 400
316Asynchronously unlink (delete) a file and call the callback with the 401Asynchronously unlink (delete) a file and call the callback with the
317result code. 402result code.
318 403
404=item aio_mknod $path, $mode, $dev, $callback->($status)
405
406[EXPERIMENTAL]
407
408Asynchronously create a device node (or fifo). See mknod(2).
409
410The only (POSIX-) portable way of calling this function is:
411
412 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
413
319=item aio_link $srcpath, $dstpath, $callback->($status) 414=item aio_link $srcpath, $dstpath, $callback->($status)
320 415
321Asynchronously create a new link to the existing object at C<$srcpath> at 416Asynchronously create a new link to the existing object at C<$srcpath> at
322the path C<$dstpath> and call the callback with the result code. 417the path C<$dstpath> and call the callback with the result code.
323 418
324=item aio_symlink $srcpath, $dstpath, $callback->($status) 419=item aio_symlink $srcpath, $dstpath, $callback->($status)
325 420
326Asynchronously create a new symbolic link to the existing object at C<$srcpath> at 421Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
327the path C<$dstpath> and call the callback with the result code. 422the path C<$dstpath> and call the callback with the result code.
423
424=item aio_readlink $path, $callback->($link)
425
426Asynchronously read the symlink specified by C<$path> and pass it to
427the callback. If an error occurs, nothing or undef gets passed to the
428callback.
328 429
329=item aio_rename $srcpath, $dstpath, $callback->($status) 430=item aio_rename $srcpath, $dstpath, $callback->($status)
330 431
331Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 432Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
332rename(2) and call the callback with the result code. 433rename(2) and call the callback with the result code.
… …
343sorted, and will B<NOT> include the C<.> and C<..> entries. 444sorted, and will B<NOT> include the C<.> and C<..> entries.
344 445
345The callback a single argument which is either C<undef> or an array-ref 446The callback a single argument which is either C<undef> or an array-ref
346with the filenames. 447with the filenames.
347 448
449=item aio_copy $srcpath, $dstpath, $callback->($status)
450
451Try to copy the I<file> (directories not supported as either source or
452destination) from C<$srcpath> to C<$dstpath> and call the callback with
453the C<0> (error) or C<-1> ok.
454
455This is a composite request that it creates the destination file with
456mode 0200 and copies the contents of the source file into it using
457C<aio_sendfile>, followed by restoring atime, mtime, access mode and
458uid/gid, in that order.
459
460If an error occurs, the partial destination file will be unlinked, if
461possible, except when setting atime, mtime, access mode and uid/gid, where
462errors are being ignored.
463
464=cut
465
466sub aio_copy($$;$) {
467 my ($src, $dst, $cb) = @_;
468
469 my $pri = aioreq_pri;
470 my $grp = aio_group $cb;
471
472 aioreq_pri $pri;
473 add $grp aio_open $src, O_RDONLY, 0, sub {
474 if (my $src_fh = $_[0]) {
475 my @stat = stat $src_fh;
476
477 aioreq_pri $pri;
478 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
479 if (my $dst_fh = $_[0]) {
480 aioreq_pri $pri;
481 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
482 if ($_[0] == $stat[7]) {
483 $grp->result (0);
484 close $src_fh;
485
486 # those should not normally block. should. should.
487 utime $stat[8], $stat[9], $dst;
488 chmod $stat[2] & 07777, $dst_fh;
489 chown $stat[4], $stat[5], $dst_fh;
490 close $dst_fh;
491 } else {
492 $grp->result (-1);
493 close $src_fh;
494 close $dst_fh;
495
496 aioreq $pri;
497 add $grp aio_unlink $dst;
498 }
499 };
500 } else {
501 $grp->result (-1);
502 }
503 },
504
505 } else {
506 $grp->result (-1);
507 }
508 };
509
510 $grp
511}
512
513=item aio_move $srcpath, $dstpath, $callback->($status)
514
515Try to move the I<file> (directories not supported as either source or
516destination) from C<$srcpath> to C<$dstpath> and call the callback with
517the C<0> (error) or C<-1> ok.
518
519This is a composite request that tries to rename(2) the file first. If
520rename files with C<EXDEV>, it copies the file with C<aio_copy> and, if
521that is successful, unlinking the C<$srcpath>.
522
523=cut
524
525sub aio_move($$;$) {
526 my ($src, $dst, $cb) = @_;
527
528 my $pri = aioreq_pri;
529 my $grp = aio_group $cb;
530
531 aioreq_pri $pri;
532 add $grp aio_rename $src, $dst, sub {
533 if ($_[0] && $! == EXDEV) {
534 aioreq_pri $pri;
535 add $grp aio_copy $src, $dst, sub {
536 $grp->result ($_[0]);
537
538 if (!$_[0]) {
539 aioreq_pri $pri;
540 add $grp aio_unlink $src;
541 }
542 };
543 } else {
544 $grp->result ($_[0]);
545 }
546 };
547
548 $grp
549}
550
348=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 551=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
349 552
350[EXPERIMENTAL due to internal aio_group use]
351
352Scans a directory (similar to C<aio_readdir>) but additionally tries to 553Scans a directory (similar to C<aio_readdir>) but additionally tries to
353separate the entries of directory C<$path> into two sets of names, ones 554efficiently separate the entries of directory C<$path> into two sets of
354you can recurse into (directories or links to them), and ones you cannot 555names, directories you can recurse into (directories), and ones you cannot
355recurse into (everything else). 556recurse into (everything else, including symlinks to directories).
356 557
357C<aio_scandir> is a composite request that consists of many sub 558C<aio_scandir> is a composite request that creates of many sub requests_
358requests. C<$maxreq> specifies the maximum number of outstanding aio 559C<$maxreq> specifies the maximum number of outstanding aio requests that
359requests that this function generates. If it is C<< <= 0 >>, then a 560this function generates. If it is C<< <= 0 >>, then a suitable default
360suitable default will be chosen (currently 8). 561will be chosen (currently 4).
361 562
362On error, the callback is called without arguments, otherwise it receives 563On error, the callback is called without arguments, otherwise it receives
363two array-refs with path-relative entry names. 564two array-refs with path-relative entry names.
364 565
365Example: 566Example:
… …
402=cut 603=cut
403 604
404sub aio_scandir($$$) { 605sub aio_scandir($$$) {
405 my ($path, $maxreq, $cb) = @_; 606 my ($path, $maxreq, $cb) = @_;
406 607
608 my $pri = aioreq_pri;
609
407 my $grp = aio_group $cb; 610 my $grp = aio_group $cb;
408 611
409 $maxreq = 8 if $maxreq <= 0; 612 $maxreq = 4 if $maxreq <= 0;
410 613
411 # stat once 614 # stat once
615 aioreq_pri $pri;
412 add $grp aio_stat $path, sub { 616 add $grp aio_stat $path, sub {
413 return $grp->result () if $_[0]; 617 return $grp->result () if $_[0];
414 my $now = time; 618 my $now = time;
415 my $hash1 = join ":", (stat _)[0,1,3,7,9]; 619 my $hash1 = join ":", (stat _)[0,1,3,7,9];
416 620
417 # read the directory entries 621 # read the directory entries
622 aioreq_pri $pri;
418 add $grp aio_readdir $path, sub { 623 add $grp aio_readdir $path, sub {
419 my $entries = shift 624 my $entries = shift
420 or return $grp->result (); 625 or return $grp->result ();
421 626
422 # stat the dir another time 627 # stat the dir another time
628 aioreq_pri $pri;
423 add $grp aio_stat $path, sub { 629 add $grp aio_stat $path, sub {
424 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 630 my $hash2 = join ":", (stat _)[0,1,3,7,9];
425 631
426 my $ndirs; 632 my $ndirs;
427 633
… …
442 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length], 648 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
443 @$entries]; 649 @$entries];
444 650
445 my (@dirs, @nondirs); 651 my (@dirs, @nondirs);
446 652
447 my ($statcb, $schedcb); 653 my $statgrp = add $grp aio_group sub {
448 my $nreq = 0; 654 $grp->result (\@dirs, \@nondirs);
655 };
449 656
450 $schedcb = sub { 657 limit $statgrp $maxreq;
451 if (@$entries) { 658 feed $statgrp sub {
452 if ($nreq < $maxreq) { 659 return unless @$entries;
453 my $ent = pop @$entries; 660 my $entry = pop @$entries;
661
662 aioreq_pri $pri;
663 add $statgrp aio_stat "$path/$entry/.", sub {
664 if ($_[0] < 0) {
665 push @nondirs, $entry;
666 } else {
667 # need to check for real directory
668 aioreq_pri $pri;
669 add $statgrp aio_lstat "$path/$entry", sub {
670 if (-d _) {
671 push @dirs, $entry;
672
673 unless (--$ndirs) {
674 push @nondirs, @$entries;
675 feed $statgrp;
676 }
677 } else {
678 push @nondirs, $entry;
679 }
454 $nreq++; 680 }
455 add $grp aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) };
456 } 681 }
457 } elsif (!$nreq) {
458 # finished
459 undef $statcb;
460 undef $schedcb;
461 $grp->result (\@dirs, \@nondirs) if $cb;
462 undef $cb;
463 } 682 };
464 }; 683 };
465 $statcb = sub {
466 my ($status, $entry) = @_;
467
468 if ($status < 0) {
469 $nreq--;
470 push @nondirs, $entry;
471 &$schedcb;
472 } else {
473 # need to check for real directory
474 add $grp aio_lstat "$path/$entry", sub {
475 $nreq--;
476
477 if (-d _) {
478 push @dirs, $entry;
479
480 if (!--$ndirs) {
481 push @nondirs, @$entries;
482 $entries = [];
483 }
484 } else {
485 push @nondirs, $entry;
486 }
487
488 &$schedcb;
489 }
490 }
491 };
492
493 &$schedcb while @$entries && $nreq < $maxreq;
494 }; 684 };
495 }; 685 };
496 }; 686 };
497 687
498 $grp 688 $grp
… …
511If this call isn't available because your OS lacks it or it couldn't be 701If this call isn't available because your OS lacks it or it couldn't be
512detected, it will be emulated by calling C<fsync> instead. 702detected, it will be emulated by calling C<fsync> instead.
513 703
514=item aio_group $callback->(...) 704=item aio_group $callback->(...)
515 705
516[EXPERIMENTAL]
517
518This is a very special aio request: Instead of doing something, it is a 706This is a very special aio request: Instead of doing something, it is a
519container for other aio requests, which is useful if you want to bundle 707container for other aio requests, which is useful if you want to bundle
520many requests into a single, composite, request. 708many requests into a single, composite, request with a definite callback
709and the ability to cancel the whole request with its subrequests.
521 710
522Returns an object of class L<IO::AIO::GRP>. See its documentation below 711Returns an object of class L<IO::AIO::GRP>. See its documentation below
523for more info. 712for more info.
524 713
525Example: 714Example:
… …
531 add $grp 720 add $grp
532 (aio_stat ...), 721 (aio_stat ...),
533 (aio_stat ...), 722 (aio_stat ...),
534 ...; 723 ...;
535 724
725=item aio_nop $callback->()
726
727This is a special request - it does nothing in itself and is only used for
728side effects, such as when you want to add a dummy request to a group so
729that finishing the requests in the group depends on executing the given
730code.
731
732While this request does nothing, it still goes through the execution
733phase and still requires a worker thread. Thus, the callback will not
734be executed immediately but only after other requests in the queue have
735entered their execution phase. This can be used to measure request
736latency.
737
536=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED* 738=item IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED*
537 739
538Mainly used for debugging and benchmarking, this aio request puts one of 740Mainly used for debugging and benchmarking, this aio request puts one of
539the request workers to sleep for the given time. 741the request workers to sleep for the given time.
540 742
541While it is theoretically handy to have simple I/O scheduling requests 743While it is theoretically handy to have simple I/O scheduling requests
542like sleep and file handle readable/writable, the overhead this creates 744like sleep and file handle readable/writable, the overhead this creates is
543is immense, so do not use this function except to put your application 745immense (it blocks a thread for a long time) so do not use this function
544under artificial I/O pressure. 746except to put your application under artificial I/O pressure.
545 747
546=back 748=back
547 749
548=head2 IO::AIO::REQ CLASS 750=head2 IO::AIO::REQ CLASS
549 751
550All non-aggregate C<aio_*> functions return an object of this class when 752All non-aggregate C<aio_*> functions return an object of this class when
551called in non-void context. 753called in non-void context.
552 754
553A request always moves through the following five states in its lifetime,
554in order: B<ready> (request has been created, but has not been executed
555yet), B<execute> (request is currently being executed), B<pending>
556(request has been executed but callback has not been called yet),
557B<result> (results are being processed synchronously, includes calling the
558callback) and B<done> (request has reached the end of its lifetime and
559holds no resources anymore).
560
561=over 4 755=over 4
562 756
563=item $req->cancel 757=item cancel $req
564 758
565Cancels the request, if possible. Has the effect of skipping execution 759Cancels the request, if possible. Has the effect of skipping execution
566when entering the B<execute> state and skipping calling the callback when 760when entering the B<execute> state and skipping calling the callback when
567entering the the B<result> state, but will leave the request otherwise 761entering the the B<result> state, but will leave the request otherwise
568untouched. That means that requests that currently execute will not be 762untouched. That means that requests that currently execute will not be
569stopped and resources held by the request will not be freed prematurely. 763stopped and resources held by the request will not be freed prematurely.
570 764
765=item cb $req $callback->(...)
766
767Replace (or simply set) the callback registered to the request.
768
571=back 769=back
572 770
573=head2 IO::AIO::GRP CLASS 771=head2 IO::AIO::GRP CLASS
574 772
575This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to 773This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to
… …
601 }; 799 };
602 800
603This makes it very easy to create composite requests (see the source of 801This makes it very easy to create composite requests (see the source of
604C<aio_move> for an application) that work and feel like simple requests. 802C<aio_move> for an application) that work and feel like simple requests.
605 803
804=over 4
805
606The IO::AIO::GRP objects will be cleaned up during calls to 806=item * The IO::AIO::GRP objects will be cleaned up during calls to
607C<IO::AIO::poll_cb>, just like any other request. 807C<IO::AIO::poll_cb>, just like any other request.
608 808
609They can be canceled like any other request. Canceling will cancel not 809=item * They can be canceled like any other request. Canceling will cancel not
610only the request itself, but also all requests it contains. 810only the request itself, but also all requests it contains.
611 811
612They can also can also be added to other IO::AIO::GRP objects. 812=item * They can also can also be added to other IO::AIO::GRP objects.
813
814=item * You must not add requests to a group from within the group callback (or
815any later time).
816
817=back
613 818
614Their lifetime, simplified, looks like this: when they are empty, they 819Their lifetime, simplified, looks like this: when they are empty, they
615will finish very quickly. If they contain only requests that are in the 820will finish very quickly. If they contain only requests that are in the
616C<done> state, they will also finish. Otherwise they will continue to 821C<done> state, they will also finish. Otherwise they will continue to
617exist. 822exist.
… …
621group. And only when all those requests have finished will the the group 826group. And only when all those requests have finished will the the group
622itself finish. 827itself finish.
623 828
624=over 4 829=over 4
625 830
831=item add $grp ...
832
626=item $grp->add (...) 833=item $grp->add (...)
627
628=item add $grp ...
629 834
630Add one or more requests to the group. Any type of L<IO::AIO::REQ> can 835Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
631be added, including other groups, as long as you do not create circular 836be added, including other groups, as long as you do not create circular
632dependencies. 837dependencies.
633 838
634Returns all its arguments. 839Returns all its arguments.
635 840
841=item $grp->cancel_subs
842
843Cancel all subrequests and clears any feeder, but not the group request
844itself. Useful when you queued a lot of events but got a result early.
845
636=item $grp->result (...) 846=item $grp->result (...)
637 847
638Set the result value(s) that will be passed to the group callback when all 848Set the result value(s) that will be passed to the group callback when all
639subrequests have finished. By default, no argument will be passed. 849subrequests have finished and set thre groups errno to the current value
850of errno (just like calling C<errno> without an error number). By default,
851no argument will be passed and errno is zero.
852
853=item $grp->errno ([$errno])
854
855Sets the group errno value to C<$errno>, or the current value of errno
856when the argument is missing.
857
858Every aio request has an associated errno value that is restored when
859the callback is invoked. This method lets you change this value from its
860default (0).
861
862Calling C<result> will also set errno, so make sure you either set C<$!>
863before the call to C<result>, or call c<errno> after it.
864
865=item feed $grp $callback->($grp)
866
867Sets a feeder/generator on this group: every group can have an attached
868generator that generates requests if idle. The idea behind this is that,
869although you could just queue as many requests as you want in a group,
870this might starve other requests for a potentially long time. For
871example, C<aio_scandir> might generate hundreds of thousands C<aio_stat>
872requests, delaying any later requests for a long time.
873
874To avoid this, and allow incremental generation of requests, you can
875instead a group and set a feeder on it that generates those requests. The
876feed callback will be called whenever there are few enough (see C<limit>,
877below) requests active in the group itself and is expected to queue more
878requests.
879
880The feed callback can queue as many requests as it likes (i.e. C<add> does
881not impose any limits).
882
883If the feed does not queue more requests when called, it will be
884automatically removed from the group.
885
886If the feed limit is C<0>, it will be set to C<2> automatically.
887
888Example:
889
890 # stat all files in @files, but only ever use four aio requests concurrently:
891
892 my $grp = aio_group sub { print "finished\n" };
893 limit $grp 4;
894 feed $grp sub {
895 my $file = pop @files
896 or return;
897
898 add $grp aio_stat $file, sub { ... };
899 };
900
901=item limit $grp $num
902
903Sets the feeder limit for the group: The feeder will be called whenever
904the group contains less than this many requests.
905
906Setting the limit to C<0> will pause the feeding process.
640 907
641=back 908=back
642 909
643=head2 SUPPORT FUNCTIONS 910=head2 SUPPORT FUNCTIONS
911
912=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
644 913
645=over 4 914=over 4
646 915
647=item $fileno = IO::AIO::poll_fileno 916=item $fileno = IO::AIO::poll_fileno
648 917
… …
653 922
654See C<poll_cb> for an example. 923See C<poll_cb> for an example.
655 924
656=item IO::AIO::poll_cb 925=item IO::AIO::poll_cb
657 926
658Process all outstanding events on the result pipe. You have to call this 927Process some outstanding events on the result pipe. You have to call this
659regularly. Returns the number of events processed. Returns immediately 928regularly. Returns the number of events processed. Returns immediately
660when no events are outstanding. 929when no events are outstanding. The amount of events processed depends on
930the settings of C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
931
932If not all requests were processed for whatever reason, the filehandle
933will still be ready when C<poll_cb> returns.
661 934
662Example: Install an Event watcher that automatically calls 935Example: Install an Event watcher that automatically calls
663IO::AIO::poll_cb with high priority: 936IO::AIO::poll_cb with high priority:
664 937
665 Event->io (fd => IO::AIO::poll_fileno, 938 Event->io (fd => IO::AIO::poll_fileno,
666 poll => 'r', async => 1, 939 poll => 'r', async => 1,
667 cb => \&IO::AIO::poll_cb); 940 cb => \&IO::AIO::poll_cb);
668 941
942=item IO::AIO::max_poll_reqs $nreqs
943
944=item IO::AIO::max_poll_time $seconds
945
946These set the maximum number of requests (default C<0>, meaning infinity)
947that are being processed by C<IO::AIO::poll_cb> in one call, respectively
948the maximum amount of time (default C<0>, meaning infinity) spent in
949C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount
950of time C<poll_cb> is allowed to use).
951
952Setting C<max_poll_time> to a non-zero value creates an overhead of one
953syscall per request processed, which is not normally a problem unless your
954callbacks are really really fast or your OS is really really slow (I am
955not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.
956
957Setting these is useful if you want to ensure some level of
958interactiveness when perl is not fast enough to process all requests in
959time.
960
961For interactive programs, values such as C<0.01> to C<0.1> should be fine.
962
963Example: Install an Event watcher that automatically calls
964IO::AIO::poll_cb with low priority, to ensure that other parts of the
965program get the CPU sometimes even under high AIO load.
966
967 # try not to spend much more than 0.1s in poll_cb
968 IO::AIO::max_poll_time 0.1;
969
970 # use a low priority so other tasks have priority
971 Event->io (fd => IO::AIO::poll_fileno,
972 poll => 'r', nice => 1,
973 cb => &IO::AIO::poll_cb);
974
669=item IO::AIO::poll_wait 975=item IO::AIO::poll_wait
670 976
977If there are any outstanding requests and none of them in the result
671Wait till the result filehandle becomes ready for reading (simply does a 978phase, wait till the result filehandle becomes ready for reading (simply
672C<select> on the filehandle. This is useful if you want to synchronously wait 979does a C<select> on the filehandle. This is useful if you want to
673for some requests to finish). 980synchronously wait for some requests to finish).
674 981
675See C<nreqs> for an example. 982See C<nreqs> for an example.
676 983
984=item IO::AIO::poll
985
986Waits until some requests have been handled.
987
988Returns the number of requests processed, but is otherwise strictly
989equivalent to:
990
991 IO::AIO::poll_wait, IO::AIO::poll_cb
992
677=item IO::AIO::nreqs 993=item IO::AIO::flush
678 994
679Returns the number of requests currently outstanding (i.e. for which their 995Wait till all outstanding AIO requests have been handled.
680callback has not been invoked yet).
681 996
682Example: wait till there are no outstanding requests anymore: 997Strictly equivalent to:
683 998
684 IO::AIO::poll_wait, IO::AIO::poll_cb 999 IO::AIO::poll_wait, IO::AIO::poll_cb
685 while IO::AIO::nreqs; 1000 while IO::AIO::nreqs;
686 1001
687=item IO::AIO::flush 1002=head3 CONTROLLING THE NUMBER OF THREADS
688
689Wait till all outstanding AIO requests have been handled.
690
691Strictly equivalent to:
692
693 IO::AIO::poll_wait, IO::AIO::poll_cb
694 while IO::AIO::nreqs;
695
696=item IO::AIO::poll
697
698Waits until some requests have been handled.
699
700Strictly equivalent to:
701
702 IO::AIO::poll_wait, IO::AIO::poll_cb
703 if IO::AIO::nreqs;
704 1003
705=item IO::AIO::min_parallel $nthreads 1004=item IO::AIO::min_parallel $nthreads
706 1005
707Set the minimum number of AIO threads to C<$nthreads>. The current default 1006Set the minimum number of AIO threads to C<$nthreads>. The current
708is C<4>, which means four asynchronous operations can be done at one time 1007default is C<8>, which means eight asynchronous operations can execute
709(the number of outstanding operations, however, is unlimited). 1008concurrently at any one time (the number of outstanding requests,
1009however, is unlimited).
710 1010
711IO::AIO starts threads only on demand, when an AIO request is queued and 1011IO::AIO starts threads only on demand, when an AIO request is queued and
712no free thread exists. 1012no free thread exists. Please note that queueing up a hundred requests can
1013create demand for a hundred threads, even if it turns out that everything
1014is in the cache and could have been processed faster by a single thread.
713 1015
714It is recommended to keep the number of threads low, as some Linux 1016It is recommended to keep the number of threads relatively low, as some
715kernel versions will scale negatively with the number of threads (higher 1017Linux kernel versions will scale negatively with the number of threads
716parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 1018(higher parallelity => MUCH higher latency). With current Linux 2.6
717threads should be fine. 1019versions, 4-32 threads should be fine.
718 1020
719Under most circumstances you don't need to call this function, as the 1021Under most circumstances you don't need to call this function, as the
720module selects a default that is suitable for low to moderate load. 1022module selects a default that is suitable for low to moderate load.
721 1023
722=item IO::AIO::max_parallel $nthreads 1024=item IO::AIO::max_parallel $nthreads
… …
731This module automatically runs C<max_parallel 0> at program end, to ensure 1033This module automatically runs C<max_parallel 0> at program end, to ensure
732that all threads are killed and that there are no outstanding requests. 1034that all threads are killed and that there are no outstanding requests.
733 1035
734Under normal circumstances you don't need to call this function. 1036Under normal circumstances you don't need to call this function.
735 1037
1038=item IO::AIO::max_idle $nthreads
1039
1040Limit the number of threads (default: 4) that are allowed to idle (i.e.,
1041threads that did not get a request to process within 10 seconds). That
1042means if a thread becomes idle while C<$nthreads> other threads are also
1043idle, it will free its resources and exit.
1044
1045This is useful when you allow a large number of threads (e.g. 100 or 1000)
1046to allow for extremely high load situations, but want to free resources
1047under normal circumstances (1000 threads can easily consume 30MB of RAM).
1048
1049The default is probably ok in most situations, especially if thread
1050creation is fast. If thread creation is very slow on your system you might
1051want to use larger values.
1052
736=item $oldnreqs = IO::AIO::max_outstanding $nreqs 1053=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
1054
1055This is a very bad function to use in interactive programs because it
1056blocks, and a bad way to reduce concurrency because it is inexact: Better
1057use an C<aio_group> together with a feed callback.
737 1058
738Sets the maximum number of outstanding requests to C<$nreqs>. If you 1059Sets the maximum number of outstanding requests to C<$nreqs>. If you
739try to queue up more than this number of requests, the caller will block until 1060to queue up more than this number of requests, the next call to the
740some requests have been handled. 1061C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
1062function will block until the limit is no longer exceeded.
741 1063
742The default is very large, so normally there is no practical limit. If you 1064The default value is very large, so there is no practical limit on the
743queue up many requests in a loop it often improves speed if you set 1065number of outstanding requests.
744this to a relatively low number, such as C<100>.
745 1066
746Under normal circumstances you don't need to call this function. 1067You can still queue as many requests as you want. Therefore,
1068C<max_oustsanding> is mainly useful in simple scripts (with low values) or
1069as a stop gap to shield against fatal memory overflow (with large values).
1070
1071=head3 STATISTICAL INFORMATION
1072
1073=item IO::AIO::nreqs
1074
1075Returns the number of requests currently in the ready, execute or pending
1076states (i.e. for which their callback has not been invoked yet).
1077
1078Example: wait till there are no outstanding requests anymore:
1079
1080 IO::AIO::poll_wait, IO::AIO::poll_cb
1081 while IO::AIO::nreqs;
1082
1083=item IO::AIO::nready
1084
1085Returns the number of requests currently in the ready state (not yet
1086executed).
1087
1088=item IO::AIO::npending
1089
1090Returns the number of requests currently in the pending state (executed,
1091but not yet processed by poll_cb).
747 1092
748=back 1093=back
749 1094
750=cut 1095=cut
751 1096
… …
763 or return undef; 1108 or return undef;
764 1109
765 *$sym 1110 *$sym
766} 1111}
767 1112
768min_parallel 4; 1113min_parallel 8;
769 1114
770END { 1115END {
771 max_parallel 0; 1116 min_parallel 1;
772} 1117 flush;
1118};
773 1119
7741; 11201;
775 1121
776=head2 FORK BEHAVIOUR 1122=head2 FORK BEHAVIOUR
777 1123
778This module should do "the right thing" when the process using it forks: 1124This module should do "the right thing" when the process using it forks:
779 1125
780Before the fork, IO::AIO enters a quiescent state where no requests 1126Before the fork, IO::AIO enters a quiescent state where no requests
781can be added in other threads and no results will be processed. After 1127can be added in other threads and no results will be processed. After
782the fork the parent simply leaves the quiescent state and continues 1128the fork the parent simply leaves the quiescent state and continues
783request/result processing, while the child clears the request/result 1129request/result processing, while the child frees the request/result queue
784queue (so the requests started before the fork will only be handled in 1130(so that the requests started before the fork will only be handled in the
785the parent). Threads will be started on demand until the limit ste in the 1131parent). Threads will be started on demand until the limit set in the
786parent process has been reached again. 1132parent process has been reached again.
787 1133
788In short: the parent will, after a short pause, continue as if fork had 1134In short: the parent will, after a short pause, continue as if fork had
789not been called, while the child will act as if IO::AIO has not been used 1135not been called, while the child will act as if IO::AIO has not been used
790yet. 1136yet.
791 1137
1138=head2 MEMORY USAGE
1139
1140Per-request usage:
1141
1142Each aio request uses - depending on your architecture - around 100-200
1143bytes of memory. In addition, stat requests need a stat buffer (possibly
1144a few hundred bytes), readdir requires a result buffer and so on. Perl
1145scalars and other data passed into aio requests will also be locked and
1146will consume memory till the request has entered the done state.
1147
1148This is now awfully much, so queuing lots of requests is not usually a
1149problem.
1150
1151Per-thread usage:
1152
1153In the execution phase, some aio requests require more memory for
1154temporary buffers, and each thread requires a stack and other data
1155structures (usually around 16k-128k, depending on the OS).
1156
1157=head1 KNOWN BUGS
1158
1159Known bugs will be fixed in the next release.
1160
792=head1 SEE ALSO 1161=head1 SEE ALSO
793 1162
794L<Coro>, L<Linux::AIO> (obsolete). 1163L<Coro::AIO>.
795 1164
796=head1 AUTHOR 1165=head1 AUTHOR
797 1166
798 Marc Lehmann <schmorp@schmorp.de> 1167 Marc Lehmann <schmorp@schmorp.de>
799 http://home.schmorp.de/ 1168 http://home.schmorp.de/

Diff Legend

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