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

Diff Legend

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