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.30 by root, Wed Aug 17 04:47:38 2005 UTC vs.
Revision 1.59 by root, Sun Oct 22 10:33:26 2006 UTC

15 15
16 aio_read $fh, 30000, 1024, $buffer, 0, sub { 16 aio_read $fh, 30000, 1024, $buffer, 0, sub {
17 $_[0] > 0 or die "read error: $!"; 17 $_[0] > 0 or die "read error: $!";
18 }; 18 };
19 19
20 # Event 20 # version 2+ has request and group objects
21 use IO::AIO 2;
22
23 my $req = aio_unlink "/tmp/file", sub { };
24 $req->cancel; # cancel request if still in queue
25
26 my $grp = aio_group sub { print "all stats done\n" };
27 add $grp aio_stat "..." for ...;
28
29 # AnyEvent integration
30 open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
31 my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
32
33 # Event integration
21 Event->io (fd => IO::AIO::poll_fileno, 34 Event->io (fd => IO::AIO::poll_fileno,
22 poll => 'r', 35 poll => 'r',
23 cb => \&IO::AIO::poll_cb); 36 cb => \&IO::AIO::poll_cb);
24 37
25 # Glib/Gtk2 38 # Glib/Gtk2 integration
26 add_watch Glib::IO IO::AIO::poll_fileno, 39 add_watch Glib::IO IO::AIO::poll_fileno,
27 in => sub { IO::AIO::poll_cb; 1 }; 40 in => sub { IO::AIO::poll_cb; 1 };
28 41
29 # Tk 42 # Tk integration
30 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "", 43 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
31 readable => \&IO::AIO::poll_cb); 44 readable => \&IO::AIO::poll_cb);
32 45
33 # Danga::Socket 46 # Danga::Socket integration
34 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno => 47 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
35 \&IO::AIO::poll_cb); 48 \&IO::AIO::poll_cb);
36
37 49
38=head1 DESCRIPTION 50=head1 DESCRIPTION
39 51
40This module implements asynchronous I/O using whatever means your 52This module implements asynchronous I/O using whatever means your
41operating system supports. 53operating system supports.
57=cut 69=cut
58 70
59package IO::AIO; 71package IO::AIO;
60 72
61no warnings; 73no warnings;
74use strict 'vars';
62 75
63use base 'Exporter'; 76use base 'Exporter';
64 77
65use Fcntl ();
66
67BEGIN { 78BEGIN {
68 $VERSION = 1.2; 79 our $VERSION = '2.0';
69 80
70 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink 81 our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
71 aio_rmdir aio_symlink aio_fsync aio_fdatasync aio_readahead); 82 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
84 aio_group);
72 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 85 our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
86
87 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
73 88
74 require XSLoader; 89 require XSLoader;
75 XSLoader::load IO::AIO, $VERSION; 90 XSLoader::load ("IO::AIO", $VERSION);
76} 91}
77 92
78=head1 FUNCTIONS 93=head1 FUNCTIONS
79 94
80=head2 AIO FUNCTIONS 95=head2 AIO FUNCTIONS
88syscall has been executed asynchronously. 103syscall has been executed asynchronously.
89 104
90All functions expecting a filehandle keep a copy of the filehandle 105All functions expecting a filehandle keep a copy of the filehandle
91internally until the request has finished. 106internally until the request has finished.
92 107
108All requests return objects of type L<IO::AIO::REQ> that allow further
109manipulation of those requests while they are in-flight.
110
93The pathnames you pass to these routines I<must> be absolute and 111The pathnames you pass to these routines I<must> be absolute and
94encoded in byte form. The reason for the former is that at the time the 112encoded in byte form. The reason for the former is that at the time the
95request is being executed, the current working directory could have 113request is being executed, the current working directory could have
96changed. Alternatively, you can make sure that you never change the 114changed. Alternatively, you can make sure that you never change the
97current working directory. 115current working directory.
103environment, d) use Glib::filename_from_unicode on unicode filenames or e) 121environment, d) use Glib::filename_from_unicode on unicode filenames or e)
104use something else. 122use something else.
105 123
106=over 4 124=over 4
107 125
108=item aio_open $pathname, $flags, $mode, $callback 126=item aio_open $pathname, $flags, $mode, $callback->($fh)
109 127
110Asynchronously open or create a file and call the callback with a newly 128Asynchronously open or create a file and call the callback with a newly
111created filehandle for the file. 129created filehandle for the file.
112 130
113The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 131The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
130 } else { 148 } else {
131 die "open failed: $!\n"; 149 die "open failed: $!\n";
132 } 150 }
133 }; 151 };
134 152
135=item aio_close $fh, $callback 153=item aio_close $fh, $callback->($status)
136 154
137Asynchronously close a file and call the callback with the result 155Asynchronously close a file and call the callback with the result
138code. I<WARNING:> although accepted, you should not pass in a perl 156code. I<WARNING:> although accepted, you should not pass in a perl
139filehandle here, as perl will likely close the file descriptor another 157filehandle here, as perl will likely close the file descriptor another
140time when the filehandle is destroyed. Normally, you can safely call perls 158time when the filehandle is destroyed. Normally, you can safely call perls
141C<close> or just let filehandles go out of scope. 159C<close> or just let filehandles go out of scope.
142 160
143This is supposed to be a bug in the API, so that might change. It's 161This is supposed to be a bug in the API, so that might change. It's
144therefore best to avoid this function. 162therefore best to avoid this function.
145 163
146=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback 164=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
147 165
148=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback 166=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
149 167
150Reads or writes C<length> bytes from the specified C<fh> and C<offset> 168Reads or writes C<length> bytes from the specified C<fh> and C<offset>
151into the scalar given by C<data> and offset C<dataoffset> and calls the 169into the scalar given by C<data> and offset C<dataoffset> and calls the
152callback without the actual number of bytes read (or -1 on error, just 170callback without the actual number of bytes read (or -1 on error, just
153like the syscall). 171like the syscall).
154 172
173The C<$data> scalar I<MUST NOT> be modified in any way while the request
174is outstanding. Modifying it can result in segfaults or WW3 (if the
175necessary/optional hardware is installed).
176
155Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at 177Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at
156offset C<0> within the scalar: 178offset C<0> within the scalar:
157 179
158 aio_read $fh, 7, 15, $buffer, 0, sub { 180 aio_read $fh, 7, 15, $buffer, 0, sub {
159 $_[0] > 0 or die "read error: $!"; 181 $_[0] > 0 or die "read error: $!";
160 print "read $_[0] bytes: <$buffer>\n"; 182 print "read $_[0] bytes: <$buffer>\n";
161 }; 183 };
162 184
185=item aio_move $srcpath, $dstpath, $callback->($status)
186
187[EXPERIMENTAL due to internal aio_group use]
188
189Try to move the I<file> (directories not supported as either source or
190destination) from C<$srcpath> to C<$dstpath> and call the callback with
191the C<0> (error) or C<-1> ok.
192
193This is a composite request that tries to rename(2) the file first. If
194rename files with C<EXDEV>, it creates the destination file with mode 0200
195and copies the contents of the source file into it using C<aio_sendfile>,
196followed by restoring atime, mtime, access mode and uid/gid, in that
197order, and unlinking the C<$srcpath>.
198
199If an error occurs, the partial destination file will be unlinked, if
200possible, except when setting atime, mtime, access mode and uid/gid, where
201errors are being ignored.
202
203=cut
204
205sub aio_move($$$) {
206 my ($src, $dst, $cb) = @_;
207
208 my $grp = aio_group $cb;
209
210 add $grp aio_rename $src, $dst, sub {
211 if ($_[0] && $! == EXDEV) {
212 add $grp aio_open $src, O_RDONLY, 0, sub {
213 if (my $src_fh = $_[0]) {
214 my @stat = stat $src_fh;
215
216 add $grp aio_open $dst, O_WRONLY, 0200, sub {
217 if (my $dst_fh = $_[0]) {
218 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
219 close $src_fh;
220
221 if ($_[0] == $stat[7]) {
222 utime $stat[8], $stat[9], $dst;
223 chmod $stat[2] & 07777, $dst_fh;
224 chown $stat[4], $stat[5], $dst_fh;
225 close $dst_fh;
226
227 add $grp aio_unlink $src, sub {
228 $grp->result ($_[0]);
229 };
230 } else {
231 my $errno = $!;
232 add $grp aio_unlink $dst, sub {
233 $! = $errno;
234 $grp->result (-1);
235 };
236 }
237 };
238 } else {
239 $grp->result (-1);
240 }
241 },
242
243 } else {
244 $grp->result (-1);
245 }
246 };
247 } else {
248 $grp->result ($_[0]);
249 }
250 };
251
252 $grp
253}
254
255=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
256
257Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
258reading at byte offset C<$in_offset>, and starts writing at the current
259file offset of C<$out_fh>. Because of that, it is not safe to issue more
260than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
261other.
262
263This call tries to make use of a native C<sendfile> syscall to provide
264zero-copy operation. For this to work, C<$out_fh> should refer to a
265socket, and C<$in_fh> should refer to mmap'able file.
266
267If the native sendfile call fails or is not implemented, it will be
268emulated, so you can call C<aio_sendfile> on any type of filehandle
269regardless of the limitations of the operating system.
270
271Please note, however, that C<aio_sendfile> can read more bytes from
272C<$in_fh> than are written, and there is no way to find out how many
273bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
274provides the number of bytes written to C<$out_fh>. Only if the result
275value equals C<$length> one can assume that C<$length> bytes have been
276read.
277
163=item aio_readahead $fh,$offset,$length, $callback 278=item aio_readahead $fh,$offset,$length, $callback->($retval)
164 279
165C<aio_readahead> populates the page cache with data from a file so that 280C<aio_readahead> populates the page cache with data from a file so that
166subsequent reads from that file will not block on disk I/O. The C<$offset> 281subsequent reads from that file will not block on disk I/O. The C<$offset>
167argument specifies the starting point from which data is to be read and 282argument specifies the starting point from which data is to be read and
168C<$length> specifies the number of bytes to be read. I/O is performed in 283C<$length> specifies the number of bytes to be read. I/O is performed in
172file. The current file offset of the file is left unchanged. 287file. The current file offset of the file is left unchanged.
173 288
174If that syscall doesn't exist (likely if your OS isn't Linux) it will be 289If that syscall doesn't exist (likely if your OS isn't Linux) it will be
175emulated by simply reading the data, which would have a similar effect. 290emulated by simply reading the data, which would have a similar effect.
176 291
177=item aio_stat $fh_or_path, $callback 292=item aio_stat $fh_or_path, $callback->($status)
178 293
179=item aio_lstat $fh, $callback 294=item aio_lstat $fh, $callback->($status)
180 295
181Works like perl's C<stat> or C<lstat> in void context. The callback will 296Works like perl's C<stat> or C<lstat> in void context. The callback will
182be called after the stat and the results will be available using C<stat _> 297be called after the stat and the results will be available using C<stat _>
183or C<-s _> etc... 298or C<-s _> etc...
184 299
194 aio_stat "/etc/passwd", sub { 309 aio_stat "/etc/passwd", sub {
195 $_[0] and die "stat failed: $!"; 310 $_[0] and die "stat failed: $!";
196 print "size is ", -s _, "\n"; 311 print "size is ", -s _, "\n";
197 }; 312 };
198 313
199=item aio_unlink $pathname, $callback 314=item aio_unlink $pathname, $callback->($status)
200 315
201Asynchronously unlink (delete) a file and call the callback with the 316Asynchronously unlink (delete) a file and call the callback with the
202result code. 317result code.
203 318
319=item aio_link $srcpath, $dstpath, $callback->($status)
320
321Asynchronously create a new link to the existing object at C<$srcpath> at
322the path C<$dstpath> and call the callback with the result code.
323
324=item aio_symlink $srcpath, $dstpath, $callback->($status)
325
326Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
327the path C<$dstpath> and call the callback with the result code.
328
329=item aio_rename $srcpath, $dstpath, $callback->($status)
330
331Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
332rename(2) and call the callback with the result code.
333
204=item aio_rmdir $pathname, $callback 334=item aio_rmdir $pathname, $callback->($status)
205 335
206Asynchronously rmdir (delete) a directory and call the callback with the 336Asynchronously rmdir (delete) a directory and call the callback with the
207result code. 337result code.
208 338
339=item aio_readdir $pathname, $callback->($entries)
340
341Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
342directory (i.e. opendir + readdir + closedir). The entries will not be
343sorted, and will B<NOT> include the C<.> and C<..> entries.
344
345The callback a single argument which is either C<undef> or an array-ref
346with the filenames.
347
348=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
349
350[EXPERIMENTAL due to internal aio_group use]
351
352Scans a directory (similar to C<aio_readdir>) but additionally tries to
353separate the entries of directory C<$path> into two sets of names, ones
354you can recurse into (directories or links to them), and ones you cannot
355recurse into (everything else).
356
357C<aio_scandir> is a composite request that consists of many sub
358requests. C<$maxreq> specifies the maximum number of outstanding aio
359requests that this function generates. If it is C<< <= 0 >>, then a
360suitable default will be chosen (currently 8).
361
362On error, the callback is called without arguments, otherwise it receives
363two array-refs with path-relative entry names.
364
365Example:
366
367 aio_scandir $dir, 0, sub {
368 my ($dirs, $nondirs) = @_;
369 print "real directories: @$dirs\n";
370 print "everything else: @$nondirs\n";
371 };
372
373Implementation notes.
374
375The C<aio_readdir> cannot be avoided, but C<stat()>'ing every entry can.
376
377After reading the directory, the modification time, size etc. of the
378directory before and after the readdir is checked, and if they match (and
379isn't the current time), the link count will be used to decide how many
380entries are directories (if >= 2). Otherwise, no knowledge of the number
381of subdirectories will be assumed.
382
383Then entries will be sorted into likely directories (everything without
384a non-initial dot currently) and likely non-directories (everything
385else). Then every entry plus an appended C</.> will be C<stat>'ed,
386likely directories first. If that succeeds, it assumes that the entry
387is a directory or a symlink to directory (which will be checked
388seperately). This is often faster than stat'ing the entry itself because
389filesystems might detect the type of the entry without reading the inode
390data (e.g. ext2fs filetype feature).
391
392If the known number of directories (link count - 2) has been reached, the
393rest of the entries is assumed to be non-directories.
394
395This only works with certainty on POSIX (= UNIX) filesystems, which
396fortunately are the vast majority of filesystems around.
397
398It will also likely work on non-POSIX filesystems with reduced efficiency
399as those tend to return 0 or 1 as link counts, which disables the
400directory counting heuristic.
401
402=cut
403
404sub aio_scandir($$$) {
405 my ($path, $maxreq, $cb) = @_;
406
407 my $grp = aio_group $cb;
408
409 $maxreq = 8 if $maxreq <= 0;
410
411 # stat once
412 add $grp aio_stat $path, sub {
413 return $grp->result () if $_[0];
414 my $now = time;
415 my $hash1 = join ":", (stat _)[0,1,3,7,9];
416
417 # read the directory entries
418 add $grp aio_readdir $path, sub {
419 my $entries = shift
420 or return $grp->result ();
421
422 # stat the dir another time
423 add $grp aio_stat $path, sub {
424 my $hash2 = join ":", (stat _)[0,1,3,7,9];
425
426 my $ndirs;
427
428 # take the slow route if anything looks fishy
429 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
430 $ndirs = -1;
431 } else {
432 # if nlink == 2, we are finished
433 # on non-posix-fs's, we rely on nlink < 2
434 $ndirs = (stat _)[3] - 2
435 or return $grp->result ([], $entries);
436 }
437
438 # sort into likely dirs and likely nondirs
439 # dirs == files without ".", short entries first
440 $entries = [map $_->[0],
441 sort { $b->[1] cmp $a->[1] }
442 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
443 @$entries];
444
445 my (@dirs, @nondirs);
446
447 my ($statcb, $schedcb);
448 my $nreq = 0;
449
450 $schedcb = sub {
451 if (@$entries) {
452 if ($nreq < $maxreq) {
453 my $ent = pop @$entries;
454 $nreq++;
455 add $grp aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) };
456 }
457 } elsif (!$nreq) {
458 # finished
459 undef $statcb;
460 undef $schedcb;
461 $grp->result (\@dirs, \@nondirs) if $cb;
462 undef $cb;
463 }
464 };
465 $statcb = sub {
466 my ($status, $entry) = @_;
467
468 if ($status < 0) {
469 $nreq--;
470 push @nondirs, $entry;
471 &$schedcb;
472 } else {
473 # need to check for real directory
474 add $grp aio_lstat "$path/$entry", sub {
475 $nreq--;
476
477 if (-d _) {
478 push @dirs, $entry;
479
480 if (!--$ndirs) {
481 push @nondirs, @$entries;
482 $entries = [];
483 }
484 } else {
485 push @nondirs, $entry;
486 }
487
488 &$schedcb;
489 }
490 }
491 };
492
493 &$schedcb while @$entries && $nreq < $maxreq;
494 };
495 };
496 };
497
498 $grp
499}
500
209=item aio_fsync $fh, $callback 501=item aio_fsync $fh, $callback->($status)
210 502
211Asynchronously call fsync on the given filehandle and call the callback 503Asynchronously call fsync on the given filehandle and call the callback
212with the fsync result code. 504with the fsync result code.
213 505
214=item aio_fdatasync $fh, $callback 506=item aio_fdatasync $fh, $callback->($status)
215 507
216Asynchronously call fdatasync on the given filehandle and call the 508Asynchronously call fdatasync on the given filehandle and call the
217callback with the fdatasync result code. 509callback with the fdatasync result code.
218 510
219If this call isn't available because your OS lacks it or it couldn't be 511If this call isn't available because your OS lacks it or it couldn't be
220detected, it will be emulated by calling C<fsync> instead. 512detected, it will be emulated by calling C<fsync> instead.
513
514=item aio_group $callback->(...)
515
516[EXPERIMENTAL]
517
518This is a very special aio request: Instead of doing something, it is a
519container for other aio requests, which is useful if you want to bundle
520many requests into a single, composite, request.
521
522Returns an object of class L<IO::AIO::GRP>. See its documentation below
523for more info.
524
525Example:
526
527 my $grp = aio_group sub {
528 print "all stats done\n";
529 };
530
531 add $grp
532 (aio_stat ...),
533 (aio_stat ...),
534 ...;
535
536=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED*
537
538Mainly used for debugging and benchmarking, this aio request puts one of
539the request workers to sleep for the given time.
540
541While it is theoretically handy to have simple I/O scheduling requests
542like sleep and file handle readable/writable, the overhead this creates
543is immense, so do not use this function except to put your application
544under artificial I/O pressure.
545
546=back
547
548=head2 IO::AIO::REQ CLASS
549
550All non-aggregate C<aio_*> functions return an object of this class when
551called in non-void context.
552
553A request always moves through the following five states in its lifetime,
554in order: B<ready> (request has been created, but has not been executed
555yet), B<execute> (request is currently being executed), B<pending>
556(request has been executed but callback has not been called yet),
557B<result> (results are being processed synchronously, includes calling the
558callback) and B<done> (request has reached the end of its lifetime and
559holds no resources anymore).
560
561=over 4
562
563=item $req->cancel
564
565Cancels the request, if possible. Has the effect of skipping execution
566when entering the B<execute> state and skipping calling the callback when
567entering the the B<result> state, but will leave the request otherwise
568untouched. That means that requests that currently execute will not be
569stopped and resources held by the request will not be freed prematurely.
570
571=back
572
573=head2 IO::AIO::GRP CLASS
574
575This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to
576objects of this class, too.
577
578A IO::AIO::GRP object is a special request that can contain multiple other
579aio requests.
580
581You create one by calling the C<aio_group> constructing function with a
582callback that will be called when all contained requests have entered the
583C<done> state:
584
585 my $grp = aio_group sub {
586 print "all requests are done\n";
587 };
588
589You add requests by calling the C<add> method with one or more
590C<IO::AIO::REQ> objects:
591
592 $grp->add (aio_unlink "...");
593
594 add $grp aio_stat "...", sub {
595 $_[0] or return $grp->result ("error");
596
597 # add another request dynamically, if first succeeded
598 add $grp aio_open "...", sub {
599 $grp->result ("ok");
600 };
601 };
602
603This makes it very easy to create composite requests (see the source of
604C<aio_move> for an application) that work and feel like simple requests.
605
606The IO::AIO::GRP objects will be cleaned up during calls to
607C<IO::AIO::poll_cb>, just like any other request.
608
609They can be canceled like any other request. Canceling will cancel not
610only the request itself, but also all requests it contains.
611
612They can also can also be added to other IO::AIO::GRP objects.
613
614Their lifetime, simplified, looks like this: when they are empty, they
615will finish very quickly. If they contain only requests that are in the
616C<done> state, they will also finish. Otherwise they will continue to
617exist.
618
619That means after creating a group you have some time to add requests. And
620in the callbacks of those requests, you can add further requests to the
621group. And only when all those requests have finished will the the group
622itself finish.
623
624=over 4
625
626=item $grp->add (...)
627
628=item add $grp ...
629
630Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
631be added, including other groups, as long as you do not create circular
632dependencies.
633
634Returns all its arguments.
635
636=item $grp->result (...)
637
638Set the result value(s) that will be passed to the group callback when all
639subrequests have finished. By default, no argument will be passed.
221 640
222=back 641=back
223 642
224=head2 SUPPORT FUNCTIONS 643=head2 SUPPORT FUNCTIONS
225 644
283 IO::AIO::poll_wait, IO::AIO::poll_cb 702 IO::AIO::poll_wait, IO::AIO::poll_cb
284 if IO::AIO::nreqs; 703 if IO::AIO::nreqs;
285 704
286=item IO::AIO::min_parallel $nthreads 705=item IO::AIO::min_parallel $nthreads
287 706
288Set the minimum number of AIO threads to C<$nthreads>. The default is 707Set the minimum number of AIO threads to C<$nthreads>. The current default
289C<1>, which means a single asynchronous operation can be done at one time 708is C<4>, which means four asynchronous operations can be done at one time
290(the number of outstanding operations, however, is unlimited). 709(the number of outstanding operations, however, is unlimited).
710
711IO::AIO starts threads only on demand, when an AIO request is queued and
712no free thread exists.
291 713
292It is recommended to keep the number of threads low, as some Linux 714It is recommended to keep the number of threads low, as some Linux
293kernel versions will scale negatively with the number of threads (higher 715kernel versions will scale negatively with the number of threads (higher
294parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 716parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
295threads should be fine. 717threads should be fine.
296 718
297Under normal circumstances you don't need to call this function, as this 719Under most circumstances you don't need to call this function, as the
298module automatically starts some threads (the exact number might change, 720module selects a default that is suitable for low to moderate load.
299and is currently 4).
300 721
301=item IO::AIO::max_parallel $nthreads 722=item IO::AIO::max_parallel $nthreads
302 723
303Sets the maximum number of AIO threads to C<$nthreads>. If more than 724Sets the maximum number of AIO threads to C<$nthreads>. If more than the
304the specified number of threads are currently running, kill them. This 725specified number of threads are currently running, this function kills
305function blocks until the limit is reached. 726them. This function blocks until the limit is reached.
727
728While C<$nthreads> are zero, aio requests get queued but not executed
729until the number of threads has been increased again.
306 730
307This module automatically runs C<max_parallel 0> at program end, to ensure 731This module automatically runs C<max_parallel 0> at program end, to ensure
308that all threads are killed and that there are no outstanding requests. 732that all threads are killed and that there are no outstanding requests.
309 733
310Under normal circumstances you don't need to call this function. 734Under normal circumstances you don't need to call this function.
314Sets the maximum number of outstanding requests to C<$nreqs>. If you 738Sets the maximum number of outstanding requests to C<$nreqs>. If you
315try to queue up more than this number of requests, the caller will block until 739try to queue up more than this number of requests, the caller will block until
316some requests have been handled. 740some requests have been handled.
317 741
318The default is very large, so normally there is no practical limit. If you 742The default is very large, so normally there is no practical limit. If you
319queue up many requests in a loop it it often improves speed if you set 743queue up many requests in a loop it often improves speed if you set
320this to a relatively low number, such as C<100>. 744this to a relatively low number, such as C<100>.
321 745
322Under normal circumstances you don't need to call this function. 746Under normal circumstances you don't need to call this function.
323 747
324=back 748=back
349 773
3501; 7741;
351 775
352=head2 FORK BEHAVIOUR 776=head2 FORK BEHAVIOUR
353 777
354Before the fork IO::AIO first handles all outstanding requests - if other 778This module should do "the right thing" when the process using it forks:
355threads add requests during this period, this time is prolonged. It then 779
356enters a quiescent state where no requests can be added in other threads 780Before the fork, IO::AIO enters a quiescent state where no requests
357and no results will be processed. After the fork the parent simply leaves 781can be added in other threads and no results will be processed. After
358the quiescent state and continues request processing, while the child 782the fork the parent simply leaves the quiescent state and continues
359starts the same number of threads as were in use by the parent. 783request/result processing, while the child clears the request/result
784queue (so the requests started before the fork will only be handled in
785the parent). Threads will be started on demand until the limit ste in the
786parent process has been reached again.
787
788In short: the parent will, after a short pause, continue as if fork had
789not been called, while the child will act as if IO::AIO has not been used
790yet.
360 791
361=head1 SEE ALSO 792=head1 SEE ALSO
362 793
363L<Coro>, L<Linux::AIO>. 794L<Coro>, L<Linux::AIO> (obsolete).
364 795
365=head1 AUTHOR 796=head1 AUTHOR
366 797
367 Marc Lehmann <schmorp@schmorp.de> 798 Marc Lehmann <schmorp@schmorp.de>
368 http://home.schmorp.de/ 799 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines