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.58 by root, Sun Oct 22 10:33:19 2006 UTC vs.
Revision 1.92 by root, Wed Nov 8 01:57:42 2006 UTC

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

Diff Legend

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