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.57 by root, Sun Oct 22 01:28:31 2006 UTC vs.
Revision 1.97 by root, Sat Dec 23 04:49:37 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.3';
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 aio_block));
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.
… …
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 339
185=item aio_move $srcpath, $dstpath, $callback->($status)
186
187Try to move the I<file> (directories not supported as either source or
188destination) from C<$srcpath> to C<$dstpath> and call the callback with
189the C<0> (error) or C<-1> ok.
190
191This is a composite request that tries to rename(2) the file first. If
192rename files with C<EXDEV>, it creates the destination file with mode 0200
193and copies the contents of the source file into it using C<aio_sendfile>,
194followed by restoring atime, mtime, access mode and uid/gid, in that
195order, and unlinking the C<$srcpath>.
196
197If an error occurs, the partial destination file will be unlinked, if
198possible, except when setting atime, mtime, access mode and uid/gid, where
199errors are being ignored.
200
201=cut
202
203sub aio_move($$$) {
204 my ($src, $dst, $cb) = @_;
205
206 my $grp = aio_group;
207
208 add $grp aio_rename $src, $dst, sub {
209 if ($_[0] && $! == EXDEV) {
210 add $grp aio_open $src, O_RDONLY, 0, sub {
211 if (my $src_fh = $_[0]) {
212 my @stat = stat $src_fh;
213
214 add $grp aio_open $dst, O_WRONLY, 0200, sub {
215 if (my $dst_fh = $_[0]) {
216 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
217 close $src_fh;
218
219 if ($_[0] == $stat[7]) {
220 utime $stat[8], $stat[9], $dst;
221 chmod $stat[2] & 07777, $dst_fh;
222 chown $stat[4], $stat[5], $dst_fh;
223 close $dst_fh;
224
225 add $grp aio_unlink $src, sub {
226 $cb->($_[0]);
227 };
228 } else {
229 my $errno = $!;
230 add $grp aio_unlink $dst, sub {
231 $! = $errno;
232 $cb->(-1);
233 };
234 }
235 };
236 } else {
237 $cb->(-1);
238 }
239 },
240
241 } else {
242 $cb->(-1);
243 }
244 };
245 } else {
246 $cb->($_[0]);
247 }
248 };
249
250 $grp
251}
252
253=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)
254 341
255Tries 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
256reading 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
257file offset of C<$out_fh>. Because of that, it is not safe to issue more 344file offset of C<$out_fh>. Because of that, it is not safe to issue more
… …
312=item aio_unlink $pathname, $callback->($status) 399=item aio_unlink $pathname, $callback->($status)
313 400
314Asynchronously unlink (delete) a file and call the callback with the 401Asynchronously unlink (delete) a file and call the callback with the
315result code. 402result code.
316 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
317=item aio_link $srcpath, $dstpath, $callback->($status) 414=item aio_link $srcpath, $dstpath, $callback->($status)
318 415
319Asynchronously 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
320the path C<$dstpath> and call the callback with the result code. 417the path C<$dstpath> and call the callback with the result code.
321 418
322=item aio_symlink $srcpath, $dstpath, $callback->($status) 419=item aio_symlink $srcpath, $dstpath, $callback->($status)
323 420
324Asynchronously 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
325the 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.
326 429
327=item aio_rename $srcpath, $dstpath, $callback->($status) 430=item aio_rename $srcpath, $dstpath, $callback->($status)
328 431
329Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 432Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
330rename(2) and call the callback with the result code. 433rename(2) and call the callback with the result code.
… …
341sorted, and will B<NOT> include the C<.> and C<..> entries. 444sorted, and will B<NOT> include the C<.> and C<..> entries.
342 445
343The 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
344with the filenames. 447with the filenames.
345 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 aio_block {
468 my ($src, $dst, $cb) = @_;
469
470 my $pri = aioreq_pri;
471 my $grp = aio_group $cb;
472
473 aioreq_pri $pri;
474 add $grp aio_open $src, O_RDONLY, 0, sub {
475 if (my $src_fh = $_[0]) {
476 my @stat = stat $src_fh;
477
478 aioreq_pri $pri;
479 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
480 if (my $dst_fh = $_[0]) {
481 aioreq_pri $pri;
482 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
483 if ($_[0] == $stat[7]) {
484 $grp->result (0);
485 close $src_fh;
486
487 # those should not normally block. should. should.
488 utime $stat[8], $stat[9], $dst;
489 chmod $stat[2] & 07777, $dst_fh;
490 chown $stat[4], $stat[5], $dst_fh;
491 close $dst_fh;
492 } else {
493 $grp->result (-1);
494 close $src_fh;
495 close $dst_fh;
496
497 aioreq $pri;
498 add $grp aio_unlink $dst;
499 }
500 };
501 } else {
502 $grp->result (-1);
503 }
504 },
505
506 } else {
507 $grp->result (-1);
508 }
509 };
510
511 $grp
512 }
513}
514
515=item aio_move $srcpath, $dstpath, $callback->($status)
516
517Try to move the I<file> (directories not supported as either source or
518destination) from C<$srcpath> to C<$dstpath> and call the callback with
519the C<0> (error) or C<-1> ok.
520
521This is a composite request that tries to rename(2) the file first. If
522rename files with C<EXDEV>, it copies the file with C<aio_copy> and, if
523that is successful, unlinking the C<$srcpath>.
524
525=cut
526
527sub aio_move($$;$) {
528 aio_block {
529 my ($src, $dst, $cb) = @_;
530
531 my $pri = aioreq_pri;
532 my $grp = aio_group $cb;
533
534 aioreq_pri $pri;
535 add $grp aio_rename $src, $dst, sub {
536 if ($_[0] && $! == EXDEV) {
537 aioreq_pri $pri;
538 add $grp aio_copy $src, $dst, sub {
539 $grp->result ($_[0]);
540
541 if (!$_[0]) {
542 aioreq_pri $pri;
543 add $grp aio_unlink $src;
544 }
545 };
546 } else {
547 $grp->result ($_[0]);
548 }
549 };
550
551 $grp
552 }
553}
554
346=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 555=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
347 556
348Scans a directory (similar to C<aio_readdir>) but additionally tries to 557Scans a directory (similar to C<aio_readdir>) but additionally tries to
349separate the entries of directory C<$path> into two sets of names, ones 558efficiently separate the entries of directory C<$path> into two sets of
350you can recurse into (directories or links to them), and ones you cannot 559names, directories you can recurse into (directories), and ones you cannot
351recurse into (everything else). 560recurse into (everything else, including symlinks to directories).
352 561
353C<aio_scandir> is a composite request that consists of many sub 562C<aio_scandir> is a composite request that creates of many sub requests_
354requests. C<$maxreq> specifies the maximum number of outstanding aio 563C<$maxreq> specifies the maximum number of outstanding aio requests that
355requests that this function generates. If it is C<< <= 0 >>, then a 564this function generates. If it is C<< <= 0 >>, then a suitable default
356suitable default will be chosen (currently 8). 565will be chosen (currently 4).
357 566
358On error, the callback is called without arguments, otherwise it receives 567On error, the callback is called without arguments, otherwise it receives
359two array-refs with path-relative entry names. 568two array-refs with path-relative entry names.
360 569
361Example: 570Example:
… …
396directory counting heuristic. 605directory counting heuristic.
397 606
398=cut 607=cut
399 608
400sub aio_scandir($$$) { 609sub aio_scandir($$$) {
610 aio_block {
401 my ($path, $maxreq, $cb) = @_; 611 my ($path, $maxreq, $cb) = @_;
402 612
613 my $pri = aioreq_pri;
614
403 my $grp = aio_group; 615 my $grp = aio_group $cb;
404 616
405 $maxreq = 8 if $maxreq <= 0; 617 $maxreq = 4 if $maxreq <= 0;
406 618
407 # stat once 619 # stat once
620 aioreq_pri $pri;
408 add $grp aio_stat $path, sub { 621 add $grp aio_stat $path, sub {
409 return $cb->() if $_[0]; 622 return $grp->result () if $_[0];
410 my $now = time; 623 my $now = time;
411 my $hash1 = join ":", (stat _)[0,1,3,7,9]; 624 my $hash1 = join ":", (stat _)[0,1,3,7,9];
412 625
413 # read the directory entries 626 # read the directory entries
627 aioreq_pri $pri;
414 add $grp aio_readdir $path, sub { 628 add $grp aio_readdir $path, sub {
415 my $entries = shift 629 my $entries = shift
416 or return $cb->(); 630 or return $grp->result ();
417 631
418 # stat the dir another time 632 # stat the dir another time
633 aioreq_pri $pri;
419 add $grp aio_stat $path, sub { 634 add $grp aio_stat $path, sub {
420 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 635 my $hash2 = join ":", (stat _)[0,1,3,7,9];
421 636
422 my $ndirs; 637 my $ndirs;
423 638
424 # take the slow route if anything looks fishy 639 # take the slow route if anything looks fishy
425 if ($hash1 ne $hash2 or (stat _)[9] == $now) { 640 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
426 $ndirs = -1; 641 $ndirs = -1;
427 } else { 642 } else {
428 # if nlink == 2, we are finished 643 # if nlink == 2, we are finished
429 # on non-posix-fs's, we rely on nlink < 2 644 # on non-posix-fs's, we rely on nlink < 2
430 $ndirs = (stat _)[3] - 2 645 $ndirs = (stat _)[3] - 2
431 or return $cb->([], $entries); 646 or return $grp->result ([], $entries);
432 }
433
434 # sort into likely dirs and likely nondirs
435 # dirs == files without ".", short entries first
436 $entries = [map $_->[0],
437 sort { $b->[1] cmp $a->[1] }
438 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
439 @$entries];
440
441 my (@dirs, @nondirs);
442
443 my ($statcb, $schedcb);
444 my $nreq = 0;
445
446 $schedcb = sub {
447 if (@$entries) {
448 if ($nreq < $maxreq) {
449 my $ent = pop @$entries;
450 $nreq++;
451 add $grp aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) };
452 }
453 } elsif (!$nreq) {
454 # finished
455 undef $statcb;
456 undef $schedcb;
457 $cb->(\@dirs, \@nondirs) if $cb;
458 undef $cb;
459 } 647 }
648
649 # sort into likely dirs and likely nondirs
650 # dirs == files without ".", short entries first
651 $entries = [map $_->[0],
652 sort { $b->[1] cmp $a->[1] }
653 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
654 @$entries];
655
656 my (@dirs, @nondirs);
657
658 my $statgrp = add $grp aio_group sub {
659 $grp->result (\@dirs, \@nondirs);
660 };
661
662 limit $statgrp $maxreq;
663 feed $statgrp sub {
664 return unless @$entries;
665 my $entry = pop @$entries;
666
667 aioreq_pri $pri;
668 add $statgrp aio_stat "$path/$entry/.", sub {
669 if ($_[0] < 0) {
670 push @nondirs, $entry;
671 } else {
672 # need to check for real directory
673 aioreq_pri $pri;
674 add $statgrp aio_lstat "$path/$entry", sub {
675 if (-d _) {
676 push @dirs, $entry;
677
678 unless (--$ndirs) {
679 push @nondirs, @$entries;
680 feed $statgrp;
681 }
682 } else {
683 push @nondirs, $entry;
684 }
685 }
686 }
687 };
688 };
460 }; 689 };
461 $statcb = sub {
462 my ($status, $entry) = @_;
463
464 if ($status < 0) {
465 $nreq--;
466 push @nondirs, $entry;
467 &$schedcb;
468 } else {
469 # need to check for real directory
470 add $grp aio_lstat "$path/$entry", sub {
471 $nreq--;
472
473 if (-d _) {
474 push @dirs, $entry;
475
476 if (!--$ndirs) {
477 push @nondirs, @$entries;
478 $entries = [];
479 }
480 } else {
481 push @nondirs, $entry;
482 }
483
484 &$schedcb;
485 }
486 }
487 };
488
489 &$schedcb while @$entries && $nreq < $maxreq;
490 }; 690 };
491 }; 691 };
692
693 $grp
492 }; 694 }
493
494 $grp
495} 695}
496 696
497=item aio_fsync $fh, $callback->($status) 697=item aio_fsync $fh, $callback->($status)
498 698
499Asynchronously call fsync on the given filehandle and call the callback 699Asynchronously call fsync on the given filehandle and call the callback
… …
505callback with the fdatasync result code. 705callback with the fdatasync result code.
506 706
507If this call isn't available because your OS lacks it or it couldn't be 707If this call isn't available because your OS lacks it or it couldn't be
508detected, it will be emulated by calling C<fsync> instead. 708detected, it will be emulated by calling C<fsync> instead.
509 709
510=item aio_group $callback->() 710=item aio_group $callback->(...)
511
512[EXPERIMENTAL]
513 711
514This is a very special aio request: Instead of doing something, it is a 712This is a very special aio request: Instead of doing something, it is a
515container for other aio requests, which is useful if you want to bundle 713container for other aio requests, which is useful if you want to bundle
516many requests into a single, composite, request. 714many requests into a single, composite, request with a definite callback
715and the ability to cancel the whole request with its subrequests.
517 716
518Returns an object of class L<IO::AIO::GRP>. See its documentation below 717Returns an object of class L<IO::AIO::GRP>. See its documentation below
519for more info. 718for more info.
520 719
521Example: 720Example:
… …
527 add $grp 726 add $grp
528 (aio_stat ...), 727 (aio_stat ...),
529 (aio_stat ...), 728 (aio_stat ...),
530 ...; 729 ...;
531 730
731=item aio_nop $callback->()
732
733This is a special request - it does nothing in itself and is only used for
734side effects, such as when you want to add a dummy request to a group so
735that finishing the requests in the group depends on executing the given
736code.
737
738While this request does nothing, it still goes through the execution
739phase and still requires a worker thread. Thus, the callback will not
740be executed immediately but only after other requests in the queue have
741entered their execution phase. This can be used to measure request
742latency.
743
532=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED* 744=item IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED*
533 745
534Mainly used for debugging and benchmarking, this aio request puts one of 746Mainly used for debugging and benchmarking, this aio request puts one of
535the request workers to sleep for the given time. 747the request workers to sleep for the given time.
536 748
537While it is theoretically handy to have simple I/O scheduling requests 749While it is theoretically handy to have simple I/O scheduling requests
538like sleep and file handle readable/writable, the overhead this creates 750like sleep and file handle readable/writable, the overhead this creates is
539is immense, so do not use this function except to put your application 751immense (it blocks a thread for a long time) so do not use this function
540under artificial I/O pressure. 752except to put your application under artificial I/O pressure.
541 753
542=back 754=back
543 755
544=head2 IO::AIO::REQ CLASS 756=head2 IO::AIO::REQ CLASS
545 757
546All non-aggregate C<aio_*> functions return an object of this class when 758All non-aggregate C<aio_*> functions return an object of this class when
547called in non-void context. 759called in non-void context.
548 760
549A request always moves through the following five states in its lifetime,
550in order: B<ready> (request has been created, but has not been executed
551yet), B<execute> (request is currently being executed), B<pending>
552(request has been executed but callback has not been called yet),
553B<result> (results are being processed synchronously, includes calling the
554callback) and B<done> (request has reached the end of its lifetime and
555holds no resources anymore).
556
557=over 4 761=over 4
558 762
559=item $req->cancel 763=item cancel $req
560 764
561Cancels the request, if possible. Has the effect of skipping execution 765Cancels the request, if possible. Has the effect of skipping execution
562when entering the B<execute> state and skipping calling the callback when 766when entering the B<execute> state and skipping calling the callback when
563entering the the B<result> state, but will leave the request otherwise 767entering the the B<result> state, but will leave the request otherwise
564untouched. That means that requests that currently execute will not be 768untouched. That means that requests that currently execute will not be
565stopped and resources held by the request will not be freed prematurely. 769stopped and resources held by the request will not be freed prematurely.
566 770
771=item cb $req $callback->(...)
772
773Replace (or simply set) the callback registered to the request.
774
567=back 775=back
568 776
569=head2 IO::AIO::GRP CLASS 777=head2 IO::AIO::GRP CLASS
570 778
571This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to 779This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to
… …
585You add requests by calling the C<add> method with one or more 793You add requests by calling the C<add> method with one or more
586C<IO::AIO::REQ> objects: 794C<IO::AIO::REQ> objects:
587 795
588 $grp->add (aio_unlink "..."); 796 $grp->add (aio_unlink "...");
589 797
590 add $grp aio_stat "...", sub { ... }; 798 add $grp aio_stat "...", sub {
799 $_[0] or return $grp->result ("error");
800
801 # add another request dynamically, if first succeeded
802 add $grp aio_open "...", sub {
803 $grp->result ("ok");
804 };
805 };
591 806
592This makes it very easy to create composite requests (see the source of 807This makes it very easy to create composite requests (see the source of
593C<aio_move> for an application) that work and feel like simple requests. 808C<aio_move> for an application) that work and feel like simple requests.
594 809
810=over 4
811
595The IO::AIO::GRP objects will be cleaned up during calls to 812=item * The IO::AIO::GRP objects will be cleaned up during calls to
596C<IO::AIO::poll_cb>, just like any other request. 813C<IO::AIO::poll_cb>, just like any other request.
597 814
598They can be canceled like any other request. Canceling will cancel not 815=item * They can be canceled like any other request. Canceling will cancel not
599just the request itself, but also all requests it contains. 816only the request itself, but also all requests it contains.
600 817
601They can also can also be added to other IO::AIO::GRP objects. 818=item * They can also can also be added to other IO::AIO::GRP objects.
819
820=item * You must not add requests to a group from within the group callback (or
821any later time).
822
823=back
602 824
603Their lifetime, simplified, looks like this: when they are empty, they 825Their lifetime, simplified, looks like this: when they are empty, they
604will finish very quickly. If they contain only requests that are in the 826will finish very quickly. If they contain only requests that are in the
605C<done> state, they will also finish. Otherwise they will continue to 827C<done> state, they will also finish. Otherwise they will continue to
606exist. 828exist.
… …
610group. And only when all those requests have finished will the the group 832group. And only when all those requests have finished will the the group
611itself finish. 833itself finish.
612 834
613=over 4 835=over 4
614 836
837=item add $grp ...
838
615=item $grp->add (...) 839=item $grp->add (...)
616
617=item add $grp ...
618 840
619Add one or more requests to the group. Any type of L<IO::AIO::REQ> can 841Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
620be added, including other groups, as long as you do not create circular 842be added, including other groups, as long as you do not create circular
621dependencies. 843dependencies.
622 844
623Returns all its arguments. 845Returns all its arguments.
624 846
847=item $grp->cancel_subs
848
849Cancel all subrequests and clears any feeder, but not the group request
850itself. Useful when you queued a lot of events but got a result early.
851
852=item $grp->result (...)
853
854Set the result value(s) that will be passed to the group callback when all
855subrequests have finished and set thre groups errno to the current value
856of errno (just like calling C<errno> without an error number). By default,
857no argument will be passed and errno is zero.
858
859=item $grp->errno ([$errno])
860
861Sets the group errno value to C<$errno>, or the current value of errno
862when the argument is missing.
863
864Every aio request has an associated errno value that is restored when
865the callback is invoked. This method lets you change this value from its
866default (0).
867
868Calling C<result> will also set errno, so make sure you either set C<$!>
869before the call to C<result>, or call c<errno> after it.
870
871=item feed $grp $callback->($grp)
872
873Sets a feeder/generator on this group: every group can have an attached
874generator that generates requests if idle. The idea behind this is that,
875although you could just queue as many requests as you want in a group,
876this might starve other requests for a potentially long time. For
877example, C<aio_scandir> might generate hundreds of thousands C<aio_stat>
878requests, delaying any later requests for a long time.
879
880To avoid this, and allow incremental generation of requests, you can
881instead a group and set a feeder on it that generates those requests. The
882feed callback will be called whenever there are few enough (see C<limit>,
883below) requests active in the group itself and is expected to queue more
884requests.
885
886The feed callback can queue as many requests as it likes (i.e. C<add> does
887not impose any limits).
888
889If the feed does not queue more requests when called, it will be
890automatically removed from the group.
891
892If the feed limit is C<0>, it will be set to C<2> automatically.
893
894Example:
895
896 # stat all files in @files, but only ever use four aio requests concurrently:
897
898 my $grp = aio_group sub { print "finished\n" };
899 limit $grp 4;
900 feed $grp sub {
901 my $file = pop @files
902 or return;
903
904 add $grp aio_stat $file, sub { ... };
905 };
906
907=item limit $grp $num
908
909Sets the feeder limit for the group: The feeder will be called whenever
910the group contains less than this many requests.
911
912Setting the limit to C<0> will pause the feeding process.
913
625=back 914=back
626 915
627=head2 SUPPORT FUNCTIONS 916=head2 SUPPORT FUNCTIONS
917
918=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
628 919
629=over 4 920=over 4
630 921
631=item $fileno = IO::AIO::poll_fileno 922=item $fileno = IO::AIO::poll_fileno
632 923
… …
637 928
638See C<poll_cb> for an example. 929See C<poll_cb> for an example.
639 930
640=item IO::AIO::poll_cb 931=item IO::AIO::poll_cb
641 932
642Process all outstanding events on the result pipe. You have to call this 933Process some outstanding events on the result pipe. You have to call this
643regularly. Returns the number of events processed. Returns immediately 934regularly. Returns the number of events processed. Returns immediately
644when no events are outstanding. 935when no events are outstanding. The amount of events processed depends on
936the settings of C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
937
938If not all requests were processed for whatever reason, the filehandle
939will still be ready when C<poll_cb> returns.
645 940
646Example: Install an Event watcher that automatically calls 941Example: Install an Event watcher that automatically calls
647IO::AIO::poll_cb with high priority: 942IO::AIO::poll_cb with high priority:
648 943
649 Event->io (fd => IO::AIO::poll_fileno, 944 Event->io (fd => IO::AIO::poll_fileno,
650 poll => 'r', async => 1, 945 poll => 'r', async => 1,
651 cb => \&IO::AIO::poll_cb); 946 cb => \&IO::AIO::poll_cb);
652 947
948=item IO::AIO::max_poll_reqs $nreqs
949
950=item IO::AIO::max_poll_time $seconds
951
952These set the maximum number of requests (default C<0>, meaning infinity)
953that are being processed by C<IO::AIO::poll_cb> in one call, respectively
954the maximum amount of time (default C<0>, meaning infinity) spent in
955C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount
956of time C<poll_cb> is allowed to use).
957
958Setting C<max_poll_time> to a non-zero value creates an overhead of one
959syscall per request processed, which is not normally a problem unless your
960callbacks are really really fast or your OS is really really slow (I am
961not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.
962
963Setting these is useful if you want to ensure some level of
964interactiveness when perl is not fast enough to process all requests in
965time.
966
967For interactive programs, values such as C<0.01> to C<0.1> should be fine.
968
969Example: Install an Event watcher that automatically calls
970IO::AIO::poll_cb with low priority, to ensure that other parts of the
971program get the CPU sometimes even under high AIO load.
972
973 # try not to spend much more than 0.1s in poll_cb
974 IO::AIO::max_poll_time 0.1;
975
976 # use a low priority so other tasks have priority
977 Event->io (fd => IO::AIO::poll_fileno,
978 poll => 'r', nice => 1,
979 cb => &IO::AIO::poll_cb);
980
653=item IO::AIO::poll_wait 981=item IO::AIO::poll_wait
654 982
983If there are any outstanding requests and none of them in the result
655Wait till the result filehandle becomes ready for reading (simply does a 984phase, wait till the result filehandle becomes ready for reading (simply
656C<select> on the filehandle. This is useful if you want to synchronously wait 985does a C<select> on the filehandle. This is useful if you want to
657for some requests to finish). 986synchronously wait for some requests to finish).
658 987
659See C<nreqs> for an example. 988See C<nreqs> for an example.
660 989
990=item IO::AIO::poll
991
992Waits until some requests have been handled.
993
994Returns the number of requests processed, but is otherwise strictly
995equivalent to:
996
997 IO::AIO::poll_wait, IO::AIO::poll_cb
998
661=item IO::AIO::nreqs 999=item IO::AIO::flush
662 1000
663Returns the number of requests currently outstanding (i.e. for which their 1001Wait till all outstanding AIO requests have been handled.
664callback has not been invoked yet).
665 1002
666Example: wait till there are no outstanding requests anymore: 1003Strictly equivalent to:
667 1004
668 IO::AIO::poll_wait, IO::AIO::poll_cb 1005 IO::AIO::poll_wait, IO::AIO::poll_cb
669 while IO::AIO::nreqs; 1006 while IO::AIO::nreqs;
670 1007
671=item IO::AIO::flush 1008=head3 CONTROLLING THE NUMBER OF THREADS
672
673Wait till all outstanding AIO requests have been handled.
674
675Strictly equivalent to:
676
677 IO::AIO::poll_wait, IO::AIO::poll_cb
678 while IO::AIO::nreqs;
679
680=item IO::AIO::poll
681
682Waits until some requests have been handled.
683
684Strictly equivalent to:
685
686 IO::AIO::poll_wait, IO::AIO::poll_cb
687 if IO::AIO::nreqs;
688 1009
689=item IO::AIO::min_parallel $nthreads 1010=item IO::AIO::min_parallel $nthreads
690 1011
691Set the minimum number of AIO threads to C<$nthreads>. The current default 1012Set the minimum number of AIO threads to C<$nthreads>. The current
692is C<4>, which means four asynchronous operations can be done at one time 1013default is C<8>, which means eight asynchronous operations can execute
693(the number of outstanding operations, however, is unlimited). 1014concurrently at any one time (the number of outstanding requests,
1015however, is unlimited).
694 1016
695IO::AIO starts threads only on demand, when an AIO request is queued and 1017IO::AIO starts threads only on demand, when an AIO request is queued and
696no free thread exists. 1018no free thread exists. Please note that queueing up a hundred requests can
1019create demand for a hundred threads, even if it turns out that everything
1020is in the cache and could have been processed faster by a single thread.
697 1021
698It is recommended to keep the number of threads low, as some Linux 1022It is recommended to keep the number of threads relatively low, as some
699kernel versions will scale negatively with the number of threads (higher 1023Linux kernel versions will scale negatively with the number of threads
700parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 1024(higher parallelity => MUCH higher latency). With current Linux 2.6
701threads should be fine. 1025versions, 4-32 threads should be fine.
702 1026
703Under most circumstances you don't need to call this function, as the 1027Under most circumstances you don't need to call this function, as the
704module selects a default that is suitable for low to moderate load. 1028module selects a default that is suitable for low to moderate load.
705 1029
706=item IO::AIO::max_parallel $nthreads 1030=item IO::AIO::max_parallel $nthreads
… …
715This module automatically runs C<max_parallel 0> at program end, to ensure 1039This module automatically runs C<max_parallel 0> at program end, to ensure
716that all threads are killed and that there are no outstanding requests. 1040that all threads are killed and that there are no outstanding requests.
717 1041
718Under normal circumstances you don't need to call this function. 1042Under normal circumstances you don't need to call this function.
719 1043
1044=item IO::AIO::max_idle $nthreads
1045
1046Limit the number of threads (default: 4) that are allowed to idle (i.e.,
1047threads that did not get a request to process within 10 seconds). That
1048means if a thread becomes idle while C<$nthreads> other threads are also
1049idle, it will free its resources and exit.
1050
1051This is useful when you allow a large number of threads (e.g. 100 or 1000)
1052to allow for extremely high load situations, but want to free resources
1053under normal circumstances (1000 threads can easily consume 30MB of RAM).
1054
1055The default is probably ok in most situations, especially if thread
1056creation is fast. If thread creation is very slow on your system you might
1057want to use larger values.
1058
720=item $oldnreqs = IO::AIO::max_outstanding $nreqs 1059=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
1060
1061This is a very bad function to use in interactive programs because it
1062blocks, and a bad way to reduce concurrency because it is inexact: Better
1063use an C<aio_group> together with a feed callback.
721 1064
722Sets the maximum number of outstanding requests to C<$nreqs>. If you 1065Sets the maximum number of outstanding requests to C<$nreqs>. If you
723try to queue up more than this number of requests, the caller will block until 1066to queue up more than this number of requests, the next call to the
724some requests have been handled. 1067C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
1068function will block until the limit is no longer exceeded.
725 1069
726The default is very large, so normally there is no practical limit. If you 1070The default value is very large, so there is no practical limit on the
727queue up many requests in a loop it often improves speed if you set 1071number of outstanding requests.
728this to a relatively low number, such as C<100>.
729 1072
730Under normal circumstances you don't need to call this function. 1073You can still queue as many requests as you want. Therefore,
1074C<max_oustsanding> is mainly useful in simple scripts (with low values) or
1075as a stop gap to shield against fatal memory overflow (with large values).
1076
1077=head3 STATISTICAL INFORMATION
1078
1079=item IO::AIO::nreqs
1080
1081Returns the number of requests currently in the ready, execute or pending
1082states (i.e. for which their callback has not been invoked yet).
1083
1084Example: wait till there are no outstanding requests anymore:
1085
1086 IO::AIO::poll_wait, IO::AIO::poll_cb
1087 while IO::AIO::nreqs;
1088
1089=item IO::AIO::nready
1090
1091Returns the number of requests currently in the ready state (not yet
1092executed).
1093
1094=item IO::AIO::npending
1095
1096Returns the number of requests currently in the pending state (executed,
1097but not yet processed by poll_cb).
731 1098
732=back 1099=back
733 1100
734=cut 1101=cut
735 1102
… …
747 or return undef; 1114 or return undef;
748 1115
749 *$sym 1116 *$sym
750} 1117}
751 1118
752min_parallel 4; 1119min_parallel 8;
753 1120
754END { 1121END { flush }
755 max_parallel 0;
756}
757 1122
7581; 11231;
759 1124
760=head2 FORK BEHAVIOUR 1125=head2 FORK BEHAVIOUR
761 1126
762This module should do "the right thing" when the process using it forks: 1127This module should do "the right thing" when the process using it forks:
763 1128
764Before the fork, IO::AIO enters a quiescent state where no requests 1129Before the fork, IO::AIO enters a quiescent state where no requests
765can be added in other threads and no results will be processed. After 1130can be added in other threads and no results will be processed. After
766the fork the parent simply leaves the quiescent state and continues 1131the fork the parent simply leaves the quiescent state and continues
767request/result processing, while the child clears the request/result 1132request/result processing, while the child frees the request/result queue
768queue (so the requests started before the fork will only be handled in 1133(so that the requests started before the fork will only be handled in the
769the parent). Threads will be started on demand until the limit ste in the 1134parent). Threads will be started on demand until the limit set in the
770parent process has been reached again. 1135parent process has been reached again.
771 1136
772In short: the parent will, after a short pause, continue as if fork had 1137In short: the parent will, after a short pause, continue as if fork had
773not been called, while the child will act as if IO::AIO has not been used 1138not been called, while the child will act as if IO::AIO has not been used
774yet. 1139yet.
775 1140
1141=head2 MEMORY USAGE
1142
1143Per-request usage:
1144
1145Each aio request uses - depending on your architecture - around 100-200
1146bytes of memory. In addition, stat requests need a stat buffer (possibly
1147a few hundred bytes), readdir requires a result buffer and so on. Perl
1148scalars and other data passed into aio requests will also be locked and
1149will consume memory till the request has entered the done state.
1150
1151This is now awfully much, so queuing lots of requests is not usually a
1152problem.
1153
1154Per-thread usage:
1155
1156In the execution phase, some aio requests require more memory for
1157temporary buffers, and each thread requires a stack and other data
1158structures (usually around 16k-128k, depending on the OS).
1159
1160=head1 KNOWN BUGS
1161
1162Known bugs will be fixed in the next release.
1163
776=head1 SEE ALSO 1164=head1 SEE ALSO
777 1165
778L<Coro>, L<Linux::AIO> (obsolete). 1166L<Coro::AIO>.
779 1167
780=head1 AUTHOR 1168=head1 AUTHOR
781 1169
782 Marc Lehmann <schmorp@schmorp.de> 1170 Marc Lehmann <schmorp@schmorp.de>
783 http://home.schmorp.de/ 1171 http://home.schmorp.de/

Diff Legend

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