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.24 by root, Sun Jul 31 18:45:48 2005 UTC vs.
Revision 1.174 by root, Sun Jan 10 20:28:43 2010 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
16 aio_read $fh, 30000, 1024, $buffer, 0, sub { 17 aio_read $fh, 30000, 1024, $buffer, 0, sub {
17 $_[0] > 0 or die "read error: $!"; 18 $_[0] > 0 or die "read error: $!";
18 }; 19 };
19 20
20 # Event 21 # version 2+ has request and group objects
22 use IO::AIO 2;
23
24 aioreq_pri 4; # give next request a very high priority
25 my $req = aio_unlink "/tmp/file", sub { };
26 $req->cancel; # cancel request if still in queue
27
28 my $grp = aio_group sub { print "all stats done\n" };
29 add $grp aio_stat "..." for ...;
30
31 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
32 use AnyEvent::AIO;
33
34 # EV integration
35 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
36
37 # Event integration
21 Event->io (fd => IO::AIO::poll_fileno, 38 Event->io (fd => IO::AIO::poll_fileno,
22 poll => 'r', 39 poll => 'r',
23 cb => \&IO::AIO::poll_cb); 40 cb => \&IO::AIO::poll_cb);
24 41
25 # Glib/Gtk2 42 # Glib/Gtk2 integration
26 add_watch Glib::IO IO::AIO::poll_fileno, 43 add_watch Glib::IO IO::AIO::poll_fileno,
27 in => sub { IO::AIO::poll_cb; 1 }; 44 in => sub { IO::AIO::poll_cb; 1 };
28 45
29 # Tk 46 # Tk integration
30 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "", 47 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
31 readable => \&IO::AIO::poll_cb); 48 readable => \&IO::AIO::poll_cb);
32 49
33 # Danga::Socket 50 # Danga::Socket integration
34 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno => 51 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
35 \&IO::AIO::poll_cb); 52 \&IO::AIO::poll_cb);
36 53
37
38=head1 DESCRIPTION 54=head1 DESCRIPTION
39 55
40This module implements asynchronous I/O using whatever means your 56This module implements asynchronous I/O using whatever means your
41operating system supports. 57operating system supports. It is implemented as an interface to C<libeio>
58(L<http://software.schmorp.de/pkg/libeio.html>).
42 59
60Asynchronous means that operations that can normally block your program
61(e.g. reading from disk) will be done asynchronously: the operation
62will still block, but you can do something else in the meantime. This
63is extremely useful for programs that need to stay interactive even
64when doing heavy I/O (GUI programs, high performance network servers
65etc.), but can also be used to easily do operations in parallel that are
66normally done sequentially, e.g. stat'ing many files, which is much faster
67on a RAID volume or over NFS when you do a number of stat operations
68concurrently.
69
70While most of this works on all types of file descriptors (for
71example sockets), using these functions on file descriptors that
72support nonblocking operation (again, sockets, pipes etc.) is
73very inefficient. Use an event loop for that (such as the L<EV>
74module): IO::AIO will naturally fit into such an event loop itself.
75
43Currently, a number of threads are started that execute your read/writes 76In this version, a number of threads are started that execute your
44and signal their completion. You don't need thread support in your libc or 77requests and signal their completion. You don't need thread support
45perl, and the threads created by this module will not be visible to the 78in perl, and the threads created by this module will not be visible
46pthreads library. In the future, this module might make use of the native 79to perl. In the future, this module might make use of the native aio
47aio functions available on many operating systems. However, they are often 80functions available on many operating systems. However, they are often
48not well-supported (Linux doesn't allow them on normal files currently, 81not well-supported or restricted (GNU/Linux doesn't allow them on normal
49for example), and they would only support aio_read and aio_write, so the 82files currently, for example), and they would only support aio_read and
50remaining functionality would have to be implemented using threads anyway. 83aio_write, so the remaining functionality would have to be implemented
84using threads anyway.
51 85
52Although the module will work with in the presence of other threads, it is 86Although the module will work in the presence of other (Perl-) threads,
53currently not reentrant, so use appropriate locking yourself, always call 87it is currently not reentrant in any way, so use appropriate locking
54C<poll_cb> from within the same thread, or never call C<poll_cb> (or other 88yourself, always call C<poll_cb> from within the same thread, or never
55C<aio_> functions) recursively. 89call C<poll_cb> (or other C<aio_> functions) recursively.
90
91=head2 EXAMPLE
92
93This is a simple example that uses the EV module and loads
94F</etc/passwd> asynchronously:
95
96 use Fcntl;
97 use EV;
98 use IO::AIO;
99
100 # register the IO::AIO callback with EV
101 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&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 EV::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 EV::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
56 184
57=cut 185=cut
58 186
59package IO::AIO; 187package IO::AIO;
60 188
61no warnings; 189use Carp ();
190
191use common::sense;
62 192
63use base 'Exporter'; 193use base 'Exporter';
64 194
65use Fcntl ();
66
67BEGIN { 195BEGIN {
68 $VERSION = 1.1; 196 our $VERSION = '3.5';
69 197
70 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink 198 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
71 aio_fsync aio_fdatasync aio_readahead); 199 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
72 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 200 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync
201 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead
202 aio_rename aio_link aio_move aio_copy aio_group
203 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
204 aio_chmod aio_utime aio_truncate
205 aio_msync aio_mtouch aio_statvfs);
206
207 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
208 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
209 min_parallel max_parallel max_idle
210 nreqs nready npending nthreads
211 max_poll_time max_poll_reqs
212 sendfile fadvise);
213
214 push @AIO_REQ, qw(aio_busy); # not exported
215
216 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
73 217
74 require XSLoader; 218 require XSLoader;
75 XSLoader::load IO::AIO, $VERSION; 219 XSLoader::load ("IO::AIO", $VERSION);
76} 220}
77 221
78=head1 FUNCTIONS 222=head1 FUNCTIONS
79 223
80=head2 AIO FUNCTIONS 224=head2 AIO REQUEST FUNCTIONS
81 225
82All the C<aio_*> calls are more or less thin wrappers around the syscall 226All the C<aio_*> calls are more or less thin wrappers around the syscall
83with the same name (sans C<aio_>). The arguments are similar or identical, 227with the same name (sans C<aio_>). The arguments are similar or identical,
84and they all accept an additional (and optional) C<$callback> argument 228and they all accept an additional (and optional) C<$callback> argument
85which must be a code reference. This code reference will get called with 229which must be a code reference. This code reference will get called with
86the syscall return code (e.g. most syscalls return C<-1> on error, unlike 230the syscall return code (e.g. most syscalls return C<-1> on error, unlike
87perl, which usually delivers "false") as it's sole argument when the given 231perl, which usually delivers "false") as its sole argument after the given
88syscall has been executed asynchronously. 232syscall has been executed asynchronously.
89 233
90All functions expecting a filehandle keep a copy of the filehandle 234All functions expecting a filehandle keep a copy of the filehandle
91internally until the request has finished. 235internally until the request has finished.
92 236
237All functions return request objects of type L<IO::AIO::REQ> that allow
238further manipulation of those requests while they are in-flight.
239
93The filenames you pass to these routines I<must> be absolute. The reason 240The pathnames you pass to these routines I<must> be absolute and
94for this is that at the time the request is being executed, the current 241encoded as octets. The reason for the former is that at the time the
95working directory could have changed. Alternatively, you can make sure 242request is being executed, the current working directory could have
96that you never change the current working directory. 243changed. Alternatively, you can make sure that you never change the
244current working directory anywhere in the program and then use relative
245paths.
246
247To encode pathnames as octets, either make sure you either: a) always pass
248in filenames you got from outside (command line, readdir etc.) without
249tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode
250your pathnames to the locale (or other) encoding in effect in the user
251environment, d) use Glib::filename_from_unicode on unicode filenames or e)
252use something else to ensure your scalar has the correct contents.
253
254This works, btw. independent of the internal UTF-8 bit, which IO::AIO
255handles correctly whether it is set or not.
97 256
98=over 4 257=over 4
99 258
259=item $prev_pri = aioreq_pri [$pri]
260
261Returns the priority value that would be used for the next request and, if
262C<$pri> is given, sets the priority for the next aio request.
263
264The default priority is C<0>, the minimum and maximum priorities are C<-4>
265and C<4>, respectively. Requests with higher priority will be serviced
266first.
267
268The priority will be reset to C<0> after each call to one of the C<aio_*>
269functions.
270
271Example: open a file with low priority, then read something from it with
272higher priority so the read request is serviced before other low priority
273open requests (potentially spamming the cache):
274
275 aioreq_pri -3;
276 aio_open ..., sub {
277 return unless $_[0];
278
279 aioreq_pri -2;
280 aio_read $_[0], ..., sub {
281 ...
282 };
283 };
284
285
286=item aioreq_nice $pri_adjust
287
288Similar to C<aioreq_pri>, but subtracts the given value from the current
289priority, so the effect is cumulative.
290
291
100=item aio_open $pathname, $flags, $mode, $callback 292=item aio_open $pathname, $flags, $mode, $callback->($fh)
101 293
102Asynchronously open or create a file and call the callback with a newly 294Asynchronously open or create a file and call the callback with a newly
103created filehandle for the file. 295created filehandle for the file.
104 296
105The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 297The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
109list. They are the same as used by C<sysopen>. 301list. They are the same as used by C<sysopen>.
110 302
111Likewise, C<$mode> specifies the mode of the newly created file, if it 303Likewise, C<$mode> specifies the mode of the newly created file, if it
112didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>, 304didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
113except that it is mandatory (i.e. use C<0> if you don't create new files, 305except that it is mandatory (i.e. use C<0> if you don't create new files,
114and C<0666> or C<0777> if you do). 306and C<0666> or C<0777> if you do). Note that the C<$mode> will be modified
307by the umask in effect then the request is being executed, so better never
308change the umask.
115 309
116Example: 310Example:
117 311
118 aio_open "/etc/passwd", O_RDONLY, 0, sub { 312 aio_open "/etc/passwd", O_RDONLY, 0, sub {
119 if ($_[0]) { 313 if ($_[0]) {
122 } else { 316 } else {
123 die "open failed: $!\n"; 317 die "open failed: $!\n";
124 } 318 }
125 }; 319 };
126 320
321
127=item aio_close $fh, $callback 322=item aio_close $fh, $callback->($status)
128 323
129Asynchronously close a file and call the callback with the result 324Asynchronously close a file and call the callback with the result
130code. I<WARNING:> although accepted, you should not pass in a perl 325code.
131filehandle here, as perl will likely close the file descriptor another
132time when the filehandle is destroyed. Normally, you can safely call perls
133C<close> or just let filehandles go out of scope.
134 326
135This is supposed to be a bug in the API, so that might change. It's 327Unfortunately, you can't do this to perl. Perl I<insists> very strongly on
136therefore best to avoid this function. 328closing the file descriptor associated with the filehandle itself.
137 329
330Therefore, C<aio_close> will not close the filehandle - instead it will
331use dup2 to overwrite the file descriptor with the write-end of a pipe
332(the pipe fd will be created on demand and will be cached).
333
334Or in other words: the file descriptor will be closed, but it will not be
335free for reuse until the perl filehandle is closed.
336
337=cut
338
138=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback 339=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
139 340
140=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback 341=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
141 342
142Reads or writes C<length> bytes from the specified C<fh> and C<offset> 343Reads or writes C<$length> bytes from or to the specified C<$fh> and
143into the scalar given by C<data> and offset C<dataoffset> and calls the 344C<$offset> into the scalar given by C<$data> and offset C<$dataoffset>
144callback without the actual number of bytes read (or -1 on error, just 345and calls the callback without the actual number of bytes read (or -1 on
145like the syscall). 346error, just like the syscall).
347
348C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to
349offset plus the actual number of bytes read.
350
351If C<$offset> is undefined, then the current file descriptor offset will
352be used (and updated), otherwise the file descriptor offset will not be
353changed by these calls.
354
355If C<$length> is undefined in C<aio_write>, use the remaining length of
356C<$data>.
357
358If C<$dataoffset> is less than zero, it will be counted from the end of
359C<$data>.
360
361The C<$data> scalar I<MUST NOT> be modified in any way while the request
362is outstanding. Modifying it can result in segfaults or World War III (if
363the necessary/optional hardware is installed).
146 364
147Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at 365Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at
148offset C<0> within the scalar: 366offset C<0> within the scalar:
149 367
150 aio_read $fh, 7, 15, $buffer, 0, sub { 368 aio_read $fh, 7, 15, $buffer, 0, sub {
151 $_[0] > 0 or die "read error: $!"; 369 $_[0] > 0 or die "read error: $!";
152 print "read $_[0] bytes: <$buffer>\n"; 370 print "read $_[0] bytes: <$buffer>\n";
153 }; 371 };
154 372
373
374=item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
375
376Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
377reading at byte offset C<$in_offset>, and starts writing at the current
378file offset of C<$out_fh>. Because of that, it is not safe to issue more
379than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
380other.
381
382This call tries to make use of a native C<sendfile> syscall to provide
383zero-copy operation. For this to work, C<$out_fh> should refer to a
384socket, and C<$in_fh> should refer to mmap'able file.
385
386If a native sendfile cannot be found or it fails with C<ENOSYS>,
387C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>,
388it will be emulated, so you can call C<aio_sendfile> on any type of
389filehandle regardless of the limitations of the operating system.
390
391Please note, however, that C<aio_sendfile> can read more bytes from
392C<$in_fh> than are written, and there is no way to find out how many
393bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
394provides the number of bytes written to C<$out_fh>. Only if the result
395value equals C<$length> one can assume that C<$length> bytes have been
396read.
397
398
155=item aio_readahead $fh,$offset,$length, $callback 399=item aio_readahead $fh,$offset,$length, $callback->($retval)
156
157Asynchronously reads the specified byte range into the page cache, using
158the C<readahead> syscall. If that syscall doesn't exist (likely if your OS
159isn't Linux) the status will be C<-1> and C<$!> is set to C<ENOSYS>.
160 400
161C<aio_readahead> populates the page cache with data from a file so that 401C<aio_readahead> populates the page cache with data from a file so that
162subsequent reads from that file will not block on disk I/O. The C<$offset> 402subsequent reads from that file will not block on disk I/O. The C<$offset>
163argument specifies the starting point from which data is to be read and 403argument specifies the starting point from which data is to be read and
164C<$length> specifies the number of bytes to be read. I/O is performed in 404C<$length> specifies the number of bytes to be read. I/O is performed in
165whole pages, so that offset is effectively rounded down to a page boundary 405whole pages, so that offset is effectively rounded down to a page boundary
166and bytes are read up to the next page boundary greater than or equal to 406and bytes are read up to the next page boundary greater than or equal to
167(off-set+length). C<aio_readahead> does not read beyond the end of the 407(off-set+length). C<aio_readahead> does not read beyond the end of the
168file. The current file offset of the file is left unchanged. 408file. The current file offset of the file is left unchanged.
169 409
410If that syscall doesn't exist (likely if your OS isn't Linux) it will be
411emulated by simply reading the data, which would have a similar effect.
412
413
170=item aio_stat $fh_or_path, $callback 414=item aio_stat $fh_or_path, $callback->($status)
171 415
172=item aio_lstat $fh, $callback 416=item aio_lstat $fh, $callback->($status)
173 417
174Works like perl's C<stat> or C<lstat> in void context. The callback will 418Works like perl's C<stat> or C<lstat> in void context. The callback will
175be called after the stat and the results will be available using C<stat _> 419be called after the stat and the results will be available using C<stat _>
176or C<-s _> etc... 420or C<-s _> etc...
177 421
187 aio_stat "/etc/passwd", sub { 431 aio_stat "/etc/passwd", sub {
188 $_[0] and die "stat failed: $!"; 432 $_[0] and die "stat failed: $!";
189 print "size is ", -s _, "\n"; 433 print "size is ", -s _, "\n";
190 }; 434 };
191 435
436
437=item aio_statvfs $fh_or_path, $callback->($statvfs)
438
439Works like the POSIX C<statvfs> or C<fstatvfs> syscalls, depending on
440whether a file handle or path was passed.
441
442On success, the callback is passed a hash reference with the following
443members: C<bsize>, C<frsize>, C<blocks>, C<bfree>, C<bavail>, C<files>,
444C<ffree>, C<favail>, C<fsid>, C<flag> and C<namemax>. On failure, C<undef>
445is passed.
446
447The following POSIX IO::AIO::ST_* constants are defined: C<ST_RDONLY> and
448C<ST_NOSUID>.
449
450The following non-POSIX IO::AIO::ST_* flag masks are defined to
451their correct value when available, or to C<0> on systems that do
452not support them: C<ST_NODEV>, C<ST_NOEXEC>, C<ST_SYNCHRONOUS>,
453C<ST_MANDLOCK>, C<ST_WRITE>, C<ST_APPEND>, C<ST_IMMUTABLE>, C<ST_NOATIME>,
454C<ST_NODIRATIME> and C<ST_RELATIME>.
455
456Example: stat C</wd> and dump out the data if successful.
457
458 aio_statvfs "/wd", sub {
459 my $f = $_[0]
460 or die "statvfs: $!";
461
462 use Data::Dumper;
463 say Dumper $f;
464 };
465
466 # result:
467 {
468 bsize => 1024,
469 bfree => 4333064312,
470 blocks => 10253828096,
471 files => 2050765568,
472 flag => 4096,
473 favail => 2042092649,
474 bavail => 4333064312,
475 ffree => 2042092649,
476 namemax => 255,
477 frsize => 1024,
478 fsid => 1810
479 }
480
481
482=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
483
484Works like perl's C<utime> function (including the special case of $atime
485and $mtime being undef). Fractional times are supported if the underlying
486syscalls support them.
487
488When called with a pathname, uses utimes(2) if available, otherwise
489utime(2). If called on a file descriptor, uses futimes(2) if available,
490otherwise returns ENOSYS, so this is not portable.
491
492Examples:
493
494 # set atime and mtime to current time (basically touch(1)):
495 aio_utime "path", undef, undef;
496 # set atime to current time and mtime to beginning of the epoch:
497 aio_utime "path", time, undef; # undef==0
498
499
500=item aio_chown $fh_or_path, $uid, $gid, $callback->($status)
501
502Works like perl's C<chown> function, except that C<undef> for either $uid
503or $gid is being interpreted as "do not change" (but -1 can also be used).
504
505Examples:
506
507 # same as "chown root path" in the shell:
508 aio_chown "path", 0, -1;
509 # same as above:
510 aio_chown "path", 0, undef;
511
512
513=item aio_truncate $fh_or_path, $offset, $callback->($status)
514
515Works like truncate(2) or ftruncate(2).
516
517
518=item aio_chmod $fh_or_path, $mode, $callback->($status)
519
520Works like perl's C<chmod> function.
521
522
192=item aio_unlink $pathname, $callback 523=item aio_unlink $pathname, $callback->($status)
193 524
194Asynchronously unlink (delete) a file and call the callback with the 525Asynchronously unlink (delete) a file and call the callback with the
195result code. 526result code.
196 527
528
529=item aio_mknod $path, $mode, $dev, $callback->($status)
530
531[EXPERIMENTAL]
532
533Asynchronously create a device node (or fifo). See mknod(2).
534
535The only (POSIX-) portable way of calling this function is:
536
537 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
538
539
540=item aio_link $srcpath, $dstpath, $callback->($status)
541
542Asynchronously create a new link to the existing object at C<$srcpath> at
543the path C<$dstpath> and call the callback with the result code.
544
545
546=item aio_symlink $srcpath, $dstpath, $callback->($status)
547
548Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
549the path C<$dstpath> and call the callback with the result code.
550
551
552=item aio_readlink $path, $callback->($link)
553
554Asynchronously read the symlink specified by C<$path> and pass it to
555the callback. If an error occurs, nothing or undef gets passed to the
556callback.
557
558
559=item aio_rename $srcpath, $dstpath, $callback->($status)
560
561Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
562rename(2) and call the callback with the result code.
563
564
565=item aio_mkdir $pathname, $mode, $callback->($status)
566
567Asynchronously mkdir (create) a directory and call the callback with
568the result code. C<$mode> will be modified by the umask at the time the
569request is executed, so do not change your umask.
570
571
572=item aio_rmdir $pathname, $callback->($status)
573
574Asynchronously rmdir (delete) a directory and call the callback with the
575result code.
576
577
578=item aio_readdir $pathname, $callback->($entries)
579
580Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
581directory (i.e. opendir + readdir + closedir). The entries will not be
582sorted, and will B<NOT> include the C<.> and C<..> entries.
583
584The callback is passed a single argument which is either C<undef> or an
585array-ref with the filenames.
586
587
588=item aio_readdirx $pathname, $flags, $callback->($entries, $flags)
589
590Quite similar to C<aio_readdir>, but the C<$flags> argument allows to tune
591behaviour and output format. In case of an error, C<$entries> will be
592C<undef>.
593
594The flags are a combination of the following constants, ORed together (the
595flags will also be passed to the callback, possibly modified):
596
597=over 4
598
599=item IO::AIO::READDIR_DENTS
600
601When this flag is off, then the callback gets an arrayref with of names
602only (as with C<aio_readdir>), otherwise it gets an arrayref with
603C<[$name, $type, $inode]> arrayrefs, each describing a single directory
604entry in more detail.
605
606C<$name> is the name of the entry.
607
608C<$type> is one of the C<IO::AIO::DT_xxx> constants:
609
610C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>,
611C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>,
612C<IO::AIO::DT_WHT>.
613
614C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to
615know, you have to run stat yourself. Also, for speed reasons, the C<$type>
616scalars are read-only: you can not modify them.
617
618C<$inode> is the inode number (which might not be exact on systems with 64
619bit inode numbers and 32 bit perls). This field has unspecified content on
620systems that do not deliver the inode information.
621
622=item IO::AIO::READDIR_DIRS_FIRST
623
624When this flag is set, then the names will be returned in an order where
625likely directories come first. This is useful when you need to quickly
626find directories, or you want to find all directories while avoiding to
627stat() each entry.
628
629If the system returns type information in readdir, then this is used
630to find directories directly. Otherwise, likely directories are files
631beginning with ".", or otherwise files with no dots, of which files with
632short names are tried first.
633
634=item IO::AIO::READDIR_STAT_ORDER
635
636When this flag is set, then the names will be returned in an order
637suitable for stat()'ing each one. That is, when you plan to stat()
638all files in the given directory, then the returned order will likely
639be fastest.
640
641If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, then
642the likely dirs come first, resulting in a less optimal stat order.
643
644=item IO::AIO::READDIR_FOUND_UNKNOWN
645
646This flag should not be set when calling C<aio_readdirx>. Instead, it
647is being set by C<aio_readdirx>, when any of the C<$type>'s found were
648C<IO::AIO::DT_UNKNOWN>. The absense of this flag therefore indicates that all
649C<$type>'s are known, which can be used to speed up some algorithms.
650
651=back
652
653
654=item aio_load $path, $data, $callback->($status)
655
656This is a composite request that tries to fully load the given file into
657memory. Status is the same as with aio_read.
658
659=cut
660
661sub aio_load($$;$) {
662 my ($path, undef, $cb) = @_;
663 my $data = \$_[1];
664
665 my $pri = aioreq_pri;
666 my $grp = aio_group $cb;
667
668 aioreq_pri $pri;
669 add $grp aio_open $path, O_RDONLY, 0, sub {
670 my $fh = shift
671 or return $grp->result (-1);
672
673 aioreq_pri $pri;
674 add $grp aio_read $fh, 0, (-s $fh), $$data, 0, sub {
675 $grp->result ($_[0]);
676 };
677 };
678
679 $grp
680}
681
682=item aio_copy $srcpath, $dstpath, $callback->($status)
683
684Try to copy the I<file> (directories not supported as either source or
685destination) from C<$srcpath> to C<$dstpath> and call the callback with
686a status of C<0> (ok) or C<-1> (error, see C<$!>).
687
688This is a composite request that creates the destination file with
689mode 0200 and copies the contents of the source file into it using
690C<aio_sendfile>, followed by restoring atime, mtime, access mode and
691uid/gid, in that order.
692
693If an error occurs, the partial destination file will be unlinked, if
694possible, except when setting atime, mtime, access mode and uid/gid, where
695errors are being ignored.
696
697=cut
698
699sub aio_copy($$;$) {
700 my ($src, $dst, $cb) = @_;
701
702 my $pri = aioreq_pri;
703 my $grp = aio_group $cb;
704
705 aioreq_pri $pri;
706 add $grp aio_open $src, O_RDONLY, 0, sub {
707 if (my $src_fh = $_[0]) {
708 my @stat = stat $src_fh; # hmm, might block over nfs?
709
710 aioreq_pri $pri;
711 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
712 if (my $dst_fh = $_[0]) {
713 aioreq_pri $pri;
714 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
715 if ($_[0] == $stat[7]) {
716 $grp->result (0);
717 close $src_fh;
718
719 my $ch = sub {
720 aioreq_pri $pri;
721 add $grp aio_chmod $dst_fh, $stat[2] & 07777, sub {
722 aioreq_pri $pri;
723 add $grp aio_chown $dst_fh, $stat[4], $stat[5], sub {
724 aioreq_pri $pri;
725 add $grp aio_close $dst_fh;
726 }
727 };
728 };
729
730 aioreq_pri $pri;
731 add $grp aio_utime $dst_fh, $stat[8], $stat[9], sub {
732 if ($_[0] < 0 && $! == ENOSYS) {
733 aioreq_pri $pri;
734 add $grp aio_utime $dst, $stat[8], $stat[9], $ch;
735 } else {
736 $ch->();
737 }
738 };
739 } else {
740 $grp->result (-1);
741 close $src_fh;
742 close $dst_fh;
743
744 aioreq $pri;
745 add $grp aio_unlink $dst;
746 }
747 };
748 } else {
749 $grp->result (-1);
750 }
751 },
752
753 } else {
754 $grp->result (-1);
755 }
756 };
757
758 $grp
759}
760
761=item aio_move $srcpath, $dstpath, $callback->($status)
762
763Try to move the I<file> (directories not supported as either source or
764destination) from C<$srcpath> to C<$dstpath> and call the callback with
765a status of C<0> (ok) or C<-1> (error, see C<$!>).
766
767This is a composite request that tries to rename(2) the file first; if
768rename fails with C<EXDEV>, it copies the file with C<aio_copy> and, if
769that is successful, unlinks the C<$srcpath>.
770
771=cut
772
773sub aio_move($$;$) {
774 my ($src, $dst, $cb) = @_;
775
776 my $pri = aioreq_pri;
777 my $grp = aio_group $cb;
778
779 aioreq_pri $pri;
780 add $grp aio_rename $src, $dst, sub {
781 if ($_[0] && $! == EXDEV) {
782 aioreq_pri $pri;
783 add $grp aio_copy $src, $dst, sub {
784 $grp->result ($_[0]);
785
786 if (!$_[0]) {
787 aioreq_pri $pri;
788 add $grp aio_unlink $src;
789 }
790 };
791 } else {
792 $grp->result ($_[0]);
793 }
794 };
795
796 $grp
797}
798
799=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
800
801Scans a directory (similar to C<aio_readdir>) but additionally tries to
802efficiently separate the entries of directory C<$path> into two sets of
803names, directories you can recurse into (directories), and ones you cannot
804recurse into (everything else, including symlinks to directories).
805
806C<aio_scandir> is a composite request that creates of many sub requests_
807C<$maxreq> specifies the maximum number of outstanding aio requests that
808this function generates. If it is C<< <= 0 >>, then a suitable default
809will be chosen (currently 4).
810
811On error, the callback is called without arguments, otherwise it receives
812two array-refs with path-relative entry names.
813
814Example:
815
816 aio_scandir $dir, 0, sub {
817 my ($dirs, $nondirs) = @_;
818 print "real directories: @$dirs\n";
819 print "everything else: @$nondirs\n";
820 };
821
822Implementation notes.
823
824The C<aio_readdir> cannot be avoided, but C<stat()>'ing every entry can.
825
826If readdir returns file type information, then this is used directly to
827find directories.
828
829Otherwise, after reading the directory, the modification time, size etc.
830of the directory before and after the readdir is checked, and if they
831match (and isn't the current time), the link count will be used to decide
832how many entries are directories (if >= 2). Otherwise, no knowledge of the
833number of subdirectories will be assumed.
834
835Then entries will be sorted into likely directories a non-initial dot
836currently) and likely non-directories (see C<aio_readdirx>). Then every
837entry plus an appended C</.> will be C<stat>'ed, likely directories first,
838in order of their inode numbers. If that succeeds, it assumes that the
839entry is a directory or a symlink to directory (which will be checked
840seperately). This is often faster than stat'ing the entry itself because
841filesystems might detect the type of the entry without reading the inode
842data (e.g. ext2fs filetype feature), even on systems that cannot return
843the filetype information on readdir.
844
845If the known number of directories (link count - 2) has been reached, the
846rest of the entries is assumed to be non-directories.
847
848This only works with certainty on POSIX (= UNIX) filesystems, which
849fortunately are the vast majority of filesystems around.
850
851It will also likely work on non-POSIX filesystems with reduced efficiency
852as those tend to return 0 or 1 as link counts, which disables the
853directory counting heuristic.
854
855=cut
856
857sub aio_scandir($$;$) {
858 my ($path, $maxreq, $cb) = @_;
859
860 my $pri = aioreq_pri;
861
862 my $grp = aio_group $cb;
863
864 $maxreq = 4 if $maxreq <= 0;
865
866 # stat once
867 aioreq_pri $pri;
868 add $grp aio_stat $path, sub {
869 return $grp->result () if $_[0];
870 my $now = time;
871 my $hash1 = join ":", (stat _)[0,1,3,7,9];
872
873 # read the directory entries
874 aioreq_pri $pri;
875 add $grp aio_readdirx $path, READDIR_DIRS_FIRST, sub {
876 my $entries = shift
877 or return $grp->result ();
878
879 # stat the dir another time
880 aioreq_pri $pri;
881 add $grp aio_stat $path, sub {
882 my $hash2 = join ":", (stat _)[0,1,3,7,9];
883
884 my $ndirs;
885
886 # take the slow route if anything looks fishy
887 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
888 $ndirs = -1;
889 } else {
890 # if nlink == 2, we are finished
891 # for non-posix-fs's, we rely on nlink < 2
892 $ndirs = (stat _)[3] - 2
893 or return $grp->result ([], $entries);
894 }
895
896 my (@dirs, @nondirs);
897
898 my $statgrp = add $grp aio_group sub {
899 $grp->result (\@dirs, \@nondirs);
900 };
901
902 limit $statgrp $maxreq;
903 feed $statgrp sub {
904 return unless @$entries;
905 my $entry = shift @$entries;
906
907 aioreq_pri $pri;
908 add $statgrp aio_stat "$path/$entry/.", sub {
909 if ($_[0] < 0) {
910 push @nondirs, $entry;
911 } else {
912 # need to check for real directory
913 aioreq_pri $pri;
914 add $statgrp aio_lstat "$path/$entry", sub {
915 if (-d _) {
916 push @dirs, $entry;
917
918 unless (--$ndirs) {
919 push @nondirs, @$entries;
920 feed $statgrp;
921 }
922 } else {
923 push @nondirs, $entry;
924 }
925 }
926 }
927 };
928 };
929 };
930 };
931 };
932
933 $grp
934}
935
936=item aio_rmtree $path, $callback->($status)
937
938Delete a directory tree starting (and including) C<$path>, return the
939status of the final C<rmdir> only. This is a composite request that
940uses C<aio_scandir> to recurse into and rmdir directories, and unlink
941everything else.
942
943=cut
944
945sub aio_rmtree;
946sub aio_rmtree($;$) {
947 my ($path, $cb) = @_;
948
949 my $pri = aioreq_pri;
950 my $grp = aio_group $cb;
951
952 aioreq_pri $pri;
953 add $grp aio_scandir $path, 0, sub {
954 my ($dirs, $nondirs) = @_;
955
956 my $dirgrp = aio_group sub {
957 add $grp aio_rmdir $path, sub {
958 $grp->result ($_[0]);
959 };
960 };
961
962 (aioreq_pri $pri), add $dirgrp aio_rmtree "$path/$_" for @$dirs;
963 (aioreq_pri $pri), add $dirgrp aio_unlink "$path/$_" for @$nondirs;
964
965 add $grp $dirgrp;
966 };
967
968 $grp
969}
970
971=item aio_sync $callback->($status)
972
973Asynchronously call sync and call the callback when finished.
974
197=item aio_fsync $fh, $callback 975=item aio_fsync $fh, $callback->($status)
198 976
199Asynchronously call fsync on the given filehandle and call the callback 977Asynchronously call fsync on the given filehandle and call the callback
200with the fsync result code. 978with the fsync result code.
201 979
202=item aio_fdatasync $fh, $callback 980=item aio_fdatasync $fh, $callback->($status)
203 981
204Asynchronously call fdatasync on the given filehandle and call the 982Asynchronously call fdatasync on the given filehandle and call the
205callback with the fdatasync result code. Might set C<$!> to C<ENOSYS> if 983callback with the fdatasync result code.
206C<fdatasync> is not available. 984
985If this call isn't available because your OS lacks it or it couldn't be
986detected, it will be emulated by calling C<fsync> instead.
987
988=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
989
990Sync the data portion of the file specified by C<$offset> and C<$length>
991to disk (but NOT the metadata), by calling the Linux-specific
992sync_file_range call. If sync_file_range is not available or it returns
993ENOSYS, then fdatasync or fsync is being substituted.
994
995C<$flags> can be a combination of C<IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE>,
996C<IO::AIO::SYNC_FILE_RANGE_WRITE> and
997C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range
998manpage for details.
999
1000=item aio_pathsync $path, $callback->($status)
1001
1002This request tries to open, fsync and close the given path. This is a
1003composite request intended to sync directories after directory operations
1004(E.g. rename). This might not work on all operating systems or have any
1005specific effect, but usually it makes sure that directory changes get
1006written to disc. It works for anything that can be opened for read-only,
1007not just directories.
1008
1009Future versions of this function might fall back to other methods when
1010C<fsync> on the directory fails (such as calling C<sync>).
1011
1012Passes C<0> when everything went ok, and C<-1> on error.
1013
1014=cut
1015
1016sub aio_pathsync($;$) {
1017 my ($path, $cb) = @_;
1018
1019 my $pri = aioreq_pri;
1020 my $grp = aio_group $cb;
1021
1022 aioreq_pri $pri;
1023 add $grp aio_open $path, O_RDONLY, 0, sub {
1024 my ($fh) = @_;
1025 if ($fh) {
1026 aioreq_pri $pri;
1027 add $grp aio_fsync $fh, sub {
1028 $grp->result ($_[0]);
1029
1030 aioreq_pri $pri;
1031 add $grp aio_close $fh;
1032 };
1033 } else {
1034 $grp->result (-1);
1035 }
1036 };
1037
1038 $grp
1039}
1040
1041=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1042
1043This is a rather advanced IO::AIO call, which only works on mmap(2)ed
1044scalars (see the L<Sys::Mmap> or L<Mmap> modules for details on this, note
1045that the scalar must only be modified in-place while an aio operation is
1046pending on it).
1047
1048It calls the C<msync> function of your OS, if available, with the memory
1049area starting at C<$offset> in the string and ending C<$length> bytes
1050later. If C<$length> is negative, counts from the end, and if C<$length>
1051is C<undef>, then it goes till the end of the string. The flags can be
1052a combination of C<IO::AIO::MS_ASYNC>, C<IO::AIO::MS_INVALIDATE> and
1053C<IO::AIO::MS_SYNC>.
1054
1055=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1056
1057This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1058scalars.
1059
1060It touches (reads or writes) all memory pages in the specified
1061range inside the scalar. All caveats and parameters are the same
1062as for C<aio_msync>, above, except for flags, which must be either
1063C<0> (which reads all pages and ensures they are instantiated) or
1064C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and
1065writing an octet from it, which dirties the page).
1066
1067=item aio_group $callback->(...)
1068
1069This is a very special aio request: Instead of doing something, it is a
1070container for other aio requests, which is useful if you want to bundle
1071many requests into a single, composite, request with a definite callback
1072and the ability to cancel the whole request with its subrequests.
1073
1074Returns an object of class L<IO::AIO::GRP>. See its documentation below
1075for more info.
1076
1077Example:
1078
1079 my $grp = aio_group sub {
1080 print "all stats done\n";
1081 };
1082
1083 add $grp
1084 (aio_stat ...),
1085 (aio_stat ...),
1086 ...;
1087
1088=item aio_nop $callback->()
1089
1090This is a special request - it does nothing in itself and is only used for
1091side effects, such as when you want to add a dummy request to a group so
1092that finishing the requests in the group depends on executing the given
1093code.
1094
1095While this request does nothing, it still goes through the execution
1096phase and still requires a worker thread. Thus, the callback will not
1097be executed immediately but only after other requests in the queue have
1098entered their execution phase. This can be used to measure request
1099latency.
1100
1101=item IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED*
1102
1103Mainly used for debugging and benchmarking, this aio request puts one of
1104the request workers to sleep for the given time.
1105
1106While it is theoretically handy to have simple I/O scheduling requests
1107like sleep and file handle readable/writable, the overhead this creates is
1108immense (it blocks a thread for a long time) so do not use this function
1109except to put your application under artificial I/O pressure.
207 1110
208=back 1111=back
209 1112
1113=head2 IO::AIO::REQ CLASS
1114
1115All non-aggregate C<aio_*> functions return an object of this class when
1116called in non-void context.
1117
1118=over 4
1119
1120=item cancel $req
1121
1122Cancels the request, if possible. Has the effect of skipping execution
1123when entering the B<execute> state and skipping calling the callback when
1124entering the the B<result> state, but will leave the request otherwise
1125untouched (with the exception of readdir). That means that requests that
1126currently execute will not be stopped and resources held by the request
1127will not be freed prematurely.
1128
1129=item cb $req $callback->(...)
1130
1131Replace (or simply set) the callback registered to the request.
1132
1133=back
1134
1135=head2 IO::AIO::GRP CLASS
1136
1137This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to
1138objects of this class, too.
1139
1140A IO::AIO::GRP object is a special request that can contain multiple other
1141aio requests.
1142
1143You create one by calling the C<aio_group> constructing function with a
1144callback that will be called when all contained requests have entered the
1145C<done> state:
1146
1147 my $grp = aio_group sub {
1148 print "all requests are done\n";
1149 };
1150
1151You add requests by calling the C<add> method with one or more
1152C<IO::AIO::REQ> objects:
1153
1154 $grp->add (aio_unlink "...");
1155
1156 add $grp aio_stat "...", sub {
1157 $_[0] or return $grp->result ("error");
1158
1159 # add another request dynamically, if first succeeded
1160 add $grp aio_open "...", sub {
1161 $grp->result ("ok");
1162 };
1163 };
1164
1165This makes it very easy to create composite requests (see the source of
1166C<aio_move> for an application) that work and feel like simple requests.
1167
1168=over 4
1169
1170=item * The IO::AIO::GRP objects will be cleaned up during calls to
1171C<IO::AIO::poll_cb>, just like any other request.
1172
1173=item * They can be canceled like any other request. Canceling will cancel not
1174only the request itself, but also all requests it contains.
1175
1176=item * They can also can also be added to other IO::AIO::GRP objects.
1177
1178=item * You must not add requests to a group from within the group callback (or
1179any later time).
1180
1181=back
1182
1183Their lifetime, simplified, looks like this: when they are empty, they
1184will finish very quickly. If they contain only requests that are in the
1185C<done> state, they will also finish. Otherwise they will continue to
1186exist.
1187
1188That means after creating a group you have some time to add requests
1189(precisely before the callback has been invoked, which is only done within
1190the C<poll_cb>). And in the callbacks of those requests, you can add
1191further requests to the group. And only when all those requests have
1192finished will the the group itself finish.
1193
1194=over 4
1195
1196=item add $grp ...
1197
1198=item $grp->add (...)
1199
1200Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
1201be added, including other groups, as long as you do not create circular
1202dependencies.
1203
1204Returns all its arguments.
1205
1206=item $grp->cancel_subs
1207
1208Cancel all subrequests and clears any feeder, but not the group request
1209itself. Useful when you queued a lot of events but got a result early.
1210
1211The group request will finish normally (you cannot add requests to the
1212group).
1213
1214=item $grp->result (...)
1215
1216Set the result value(s) that will be passed to the group callback when all
1217subrequests have finished and set the groups errno to the current value
1218of errno (just like calling C<errno> without an error number). By default,
1219no argument will be passed and errno is zero.
1220
1221=item $grp->errno ([$errno])
1222
1223Sets the group errno value to C<$errno>, or the current value of errno
1224when the argument is missing.
1225
1226Every aio request has an associated errno value that is restored when
1227the callback is invoked. This method lets you change this value from its
1228default (0).
1229
1230Calling C<result> will also set errno, so make sure you either set C<$!>
1231before the call to C<result>, or call c<errno> after it.
1232
1233=item feed $grp $callback->($grp)
1234
1235Sets a feeder/generator on this group: every group can have an attached
1236generator that generates requests if idle. The idea behind this is that,
1237although you could just queue as many requests as you want in a group,
1238this might starve other requests for a potentially long time. For example,
1239C<aio_scandir> might generate hundreds of thousands C<aio_stat> requests,
1240delaying any later requests for a long time.
1241
1242To avoid this, and allow incremental generation of requests, you can
1243instead a group and set a feeder on it that generates those requests. The
1244feed callback will be called whenever there are few enough (see C<limit>,
1245below) requests active in the group itself and is expected to queue more
1246requests.
1247
1248The feed callback can queue as many requests as it likes (i.e. C<add> does
1249not impose any limits).
1250
1251If the feed does not queue more requests when called, it will be
1252automatically removed from the group.
1253
1254If the feed limit is C<0> when this method is called, it will be set to
1255C<2> automatically.
1256
1257Example:
1258
1259 # stat all files in @files, but only ever use four aio requests concurrently:
1260
1261 my $grp = aio_group sub { print "finished\n" };
1262 limit $grp 4;
1263 feed $grp sub {
1264 my $file = pop @files
1265 or return;
1266
1267 add $grp aio_stat $file, sub { ... };
1268 };
1269
1270=item limit $grp $num
1271
1272Sets the feeder limit for the group: The feeder will be called whenever
1273the group contains less than this many requests.
1274
1275Setting the limit to C<0> will pause the feeding process.
1276
1277The default value for the limit is C<0>, but note that setting a feeder
1278automatically bumps it up to C<2>.
1279
1280=back
1281
210=head2 SUPPORT FUNCTIONS 1282=head2 SUPPORT FUNCTIONS
211 1283
1284=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1285
212=over 4 1286=over 4
213 1287
214=item $fileno = IO::AIO::poll_fileno 1288=item $fileno = IO::AIO::poll_fileno
215 1289
216Return the I<request result pipe file descriptor>. This filehandle must be 1290Return the I<request result pipe file descriptor>. This filehandle must be
217polled for reading by some mechanism outside this module (e.g. Event or 1291polled for reading by some mechanism outside this module (e.g. EV, Glib,
218select, see below or the SYNOPSIS). If the pipe becomes readable you have 1292select and so on, see below or the SYNOPSIS). If the pipe becomes readable
219to call C<poll_cb> to check the results. 1293you have to call C<poll_cb> to check the results.
220 1294
221See C<poll_cb> for an example. 1295See C<poll_cb> for an example.
222 1296
223=item IO::AIO::poll_cb 1297=item IO::AIO::poll_cb
224 1298
225Process all outstanding events on the result pipe. You have to call this 1299Process some outstanding events on the result pipe. You have to call this
226regularly. Returns the number of events processed. Returns immediately 1300regularly. Returns C<0> if all events could be processed, or C<-1> if it
227when no events are outstanding. 1301returned earlier for whatever reason. Returns immediately when no events
1302are outstanding. The amount of events processed depends on the settings of
1303C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
1304
1305If not all requests were processed for whatever reason, the filehandle
1306will still be ready when C<poll_cb> returns, so normally you don't have to
1307do anything special to have it called later.
228 1308
229Example: Install an Event watcher that automatically calls 1309Example: Install an Event watcher that automatically calls
230IO::AIO::poll_cb with high priority: 1310IO::AIO::poll_cb with high priority (more examples can be found in the
1311SYNOPSIS section, at the top of this document):
231 1312
232 Event->io (fd => IO::AIO::poll_fileno, 1313 Event->io (fd => IO::AIO::poll_fileno,
233 poll => 'r', async => 1, 1314 poll => 'r', async => 1,
234 cb => \&IO::AIO::poll_cb); 1315 cb => \&IO::AIO::poll_cb);
235 1316
1317=item IO::AIO::max_poll_reqs $nreqs
1318
1319=item IO::AIO::max_poll_time $seconds
1320
1321These set the maximum number of requests (default C<0>, meaning infinity)
1322that are being processed by C<IO::AIO::poll_cb> in one call, respectively
1323the maximum amount of time (default C<0>, meaning infinity) spent in
1324C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount
1325of time C<poll_cb> is allowed to use).
1326
1327Setting C<max_poll_time> to a non-zero value creates an overhead of one
1328syscall per request processed, which is not normally a problem unless your
1329callbacks are really really fast or your OS is really really slow (I am
1330not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.
1331
1332Setting these is useful if you want to ensure some level of
1333interactiveness when perl is not fast enough to process all requests in
1334time.
1335
1336For interactive programs, values such as C<0.01> to C<0.1> should be fine.
1337
1338Example: Install an Event watcher that automatically calls
1339IO::AIO::poll_cb with low priority, to ensure that other parts of the
1340program get the CPU sometimes even under high AIO load.
1341
1342 # try not to spend much more than 0.1s in poll_cb
1343 IO::AIO::max_poll_time 0.1;
1344
1345 # use a low priority so other tasks have priority
1346 Event->io (fd => IO::AIO::poll_fileno,
1347 poll => 'r', nice => 1,
1348 cb => &IO::AIO::poll_cb);
1349
236=item IO::AIO::poll_wait 1350=item IO::AIO::poll_wait
237 1351
1352If there are any outstanding requests and none of them in the result
238Wait till the result filehandle becomes ready for reading (simply does a 1353phase, wait till the result filehandle becomes ready for reading (simply
239C<select> on the filehandle. This is useful if you want to synchronously wait 1354does a C<select> on the filehandle. This is useful if you want to
240for some requests to finish). 1355synchronously wait for some requests to finish).
241 1356
242See C<nreqs> for an example. 1357See C<nreqs> for an example.
243 1358
1359=item IO::AIO::poll
1360
1361Waits until some requests have been handled.
1362
1363Returns the number of requests processed, but is otherwise strictly
1364equivalent to:
1365
1366 IO::AIO::poll_wait, IO::AIO::poll_cb
1367
244=item IO::AIO::nreqs 1368=item IO::AIO::flush
245 1369
246Returns the number of requests currently outstanding (i.e. for which their 1370Wait till all outstanding AIO requests have been handled.
247callback has not been invoked yet).
248 1371
249Example: wait till there are no outstanding requests anymore: 1372Strictly equivalent to:
250 1373
251 IO::AIO::poll_wait, IO::AIO::poll_cb 1374 IO::AIO::poll_wait, IO::AIO::poll_cb
252 while IO::AIO::nreqs; 1375 while IO::AIO::nreqs;
253 1376
1377=back
1378
1379=head3 CONTROLLING THE NUMBER OF THREADS
1380
1381=over
1382
1383=item IO::AIO::min_parallel $nthreads
1384
1385Set the minimum number of AIO threads to C<$nthreads>. The current
1386default is C<8>, which means eight asynchronous operations can execute
1387concurrently at any one time (the number of outstanding requests,
1388however, is unlimited).
1389
1390IO::AIO starts threads only on demand, when an AIO request is queued and
1391no free thread exists. Please note that queueing up a hundred requests can
1392create demand for a hundred threads, even if it turns out that everything
1393is in the cache and could have been processed faster by a single thread.
1394
1395It is recommended to keep the number of threads relatively low, as some
1396Linux kernel versions will scale negatively with the number of threads
1397(higher parallelity => MUCH higher latency). With current Linux 2.6
1398versions, 4-32 threads should be fine.
1399
1400Under most circumstances you don't need to call this function, as the
1401module selects a default that is suitable for low to moderate load.
1402
1403=item IO::AIO::max_parallel $nthreads
1404
1405Sets the maximum number of AIO threads to C<$nthreads>. If more than the
1406specified number of threads are currently running, this function kills
1407them. This function blocks until the limit is reached.
1408
1409While C<$nthreads> are zero, aio requests get queued but not executed
1410until the number of threads has been increased again.
1411
1412This module automatically runs C<max_parallel 0> at program end, to ensure
1413that all threads are killed and that there are no outstanding requests.
1414
1415Under normal circumstances you don't need to call this function.
1416
1417=item IO::AIO::max_idle $nthreads
1418
1419Limit the number of threads (default: 4) that are allowed to idle (i.e.,
1420threads that did not get a request to process within 10 seconds). That
1421means if a thread becomes idle while C<$nthreads> other threads are also
1422idle, it will free its resources and exit.
1423
1424This is useful when you allow a large number of threads (e.g. 100 or 1000)
1425to allow for extremely high load situations, but want to free resources
1426under normal circumstances (1000 threads can easily consume 30MB of RAM).
1427
1428The default is probably ok in most situations, especially if thread
1429creation is fast. If thread creation is very slow on your system you might
1430want to use larger values.
1431
1432=item IO::AIO::max_outstanding $maxreqs
1433
1434This is a very bad function to use in interactive programs because it
1435blocks, and a bad way to reduce concurrency because it is inexact: Better
1436use an C<aio_group> together with a feed callback.
1437
1438Sets the maximum number of outstanding requests to C<$nreqs>. If you
1439do queue up more than this number of requests, the next call to the
1440C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
1441function will block until the limit is no longer exceeded.
1442
1443The default value is very large, so there is no practical limit on the
1444number of outstanding requests.
1445
1446You can still queue as many requests as you want. Therefore,
1447C<max_outstanding> is mainly useful in simple scripts (with low values) or
1448as a stop gap to shield against fatal memory overflow (with large values).
1449
1450=back
1451
1452=head3 STATISTICAL INFORMATION
1453
1454=over
1455
254=item IO::AIO::flush 1456=item IO::AIO::nreqs
255 1457
256Wait till all outstanding AIO requests have been handled. 1458Returns the number of requests currently in the ready, execute or pending
1459states (i.e. for which their callback has not been invoked yet).
257 1460
258Strictly equivalent to: 1461Example: wait till there are no outstanding requests anymore:
259 1462
260 IO::AIO::poll_wait, IO::AIO::poll_cb 1463 IO::AIO::poll_wait, IO::AIO::poll_cb
261 while IO::AIO::nreqs; 1464 while IO::AIO::nreqs;
262 1465
1466=item IO::AIO::nready
1467
1468Returns the number of requests currently in the ready state (not yet
1469executed).
1470
263=item IO::AIO::poll 1471=item IO::AIO::npending
264 1472
265Waits until some requests have been handled. 1473Returns the number of requests currently in the pending state (executed,
266 1474but not yet processed by poll_cb).
267Strictly equivalent to:
268
269 IO::AIO::poll_wait, IO::AIO::poll_cb
270 if IO::AIO::nreqs;
271
272=item IO::AIO::min_parallel $nthreads
273
274Set the minimum number of AIO threads to C<$nthreads>. The default is
275C<1>, which means a single asynchronous operation can be done at one time
276(the number of outstanding operations, however, is unlimited).
277
278It is recommended to keep the number of threads low, as some Linux
279kernel versions will scale negatively with the number of threads (higher
280parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
281threads should be fine.
282
283Under normal circumstances you don't need to call this function, as this
284module automatically starts some threads (the exact number might change,
285and is currently 4).
286
287=item IO::AIO::max_parallel $nthreads
288
289Sets the maximum number of AIO threads to C<$nthreads>. If more than
290the specified number of threads are currently running, kill them. This
291function blocks until the limit is reached.
292
293This module automatically runs C<max_parallel 0> at program end, to ensure
294that all threads are killed and that there are no outstanding requests.
295
296Under normal circumstances you don't need to call this function.
297
298=item $oldnreqs = IO::AIO::max_outstanding $nreqs
299
300Sets the maximum number of outstanding requests to C<$nreqs>. If you
301try to queue up more than this number of requests, the caller will block until
302some requests have been handled.
303
304The default is very large, so normally there is no practical limit. If you
305queue up many requests in a loop it it often improves speed if you set
306this to a relatively low number, such as C<100>.
307
308Under normal circumstances you don't need to call this function.
309 1475
310=back 1476=back
311 1477
1478=head3 MISCELLANEOUS FUNCTIONS
1479
1480IO::AIO implements some functions that might be useful, but are not
1481asynchronous.
1482
1483=over 4
1484
1485=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1486
1487Calls the C<eio_sendfile_sync> function, which is like C<aio_sendfile>,
1488but is blocking (this makes most sense if you know the input data is
1489likely cached already and the output filehandle is set to non-blocking
1490operations).
1491
1492Returns the number of bytes copied, or C<-1> on error.
1493
1494=item IO::AIO::fadvise $fh, $offset, $len, $advice
1495
1496Simply calls the C<posix_fadvise> function (see it's
1497manpage for details). The following advice constants are
1498avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1499C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1500C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1501
1502On systems that do not implement C<posix_fadvise>, this function returns
1503ENOSYS, otherwise the return value of C<posix_fadvise>.
1504
1505=item IO::AIO::mlockall $flags
1506
1507Calls the C<mlockall> function with the given C<$flags> (a combination of
1508C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>).
1509
1510On systems that do not implement C<mlockall>, this function returns
1511ENOSYS, otherwise the return value of C<mlockall>.
1512
1513=item IO::AIO::munlockall
1514
1515Calls the C<munlockall> function.
1516
1517On systems that do not implement C<munlockall>, this function returns
1518ENOSYS, otherwise the return value of C<munlockall>.
1519
1520=back
1521
312=cut 1522=cut
313 1523
314# support function to convert a fd into a perl filehandle
315sub _fd2fh {
316 return undef if $_[0] < 0;
317
318 # try to generate nice filehandles
319 my $sym = "IO::AIO::fd#$_[0]";
320 local *$sym;
321 open *$sym, "+<&=$_[0]"
322 or return undef;
323
324 *$sym
325}
326
327min_parallel 4; 1524min_parallel 8;
328 1525
329END { 1526END { flush }
330 max_parallel 0;
331}
332 1527
3331; 15281;
334 1529
1530=head2 FORK BEHAVIOUR
1531
1532This module should do "the right thing" when the process using it forks:
1533
1534Before the fork, IO::AIO enters a quiescent state where no requests
1535can be added in other threads and no results will be processed. After
1536the fork the parent simply leaves the quiescent state and continues
1537request/result processing, while the child frees the request/result queue
1538(so that the requests started before the fork will only be handled in the
1539parent). Threads will be started on demand until the limit set in the
1540parent process has been reached again.
1541
1542In short: the parent will, after a short pause, continue as if fork had
1543not been called, while the child will act as if IO::AIO has not been used
1544yet.
1545
1546=head2 MEMORY USAGE
1547
1548Per-request usage:
1549
1550Each aio request uses - depending on your architecture - around 100-200
1551bytes of memory. In addition, stat requests need a stat buffer (possibly
1552a few hundred bytes), readdir requires a result buffer and so on. Perl
1553scalars and other data passed into aio requests will also be locked and
1554will consume memory till the request has entered the done state.
1555
1556This is not awfully much, so queuing lots of requests is not usually a
1557problem.
1558
1559Per-thread usage:
1560
1561In the execution phase, some aio requests require more memory for
1562temporary buffers, and each thread requires a stack and other data
1563structures (usually around 16k-128k, depending on the OS).
1564
1565=head1 KNOWN BUGS
1566
1567Known bugs will be fixed in the next release.
1568
335=head1 SEE ALSO 1569=head1 SEE ALSO
336 1570
337L<Coro>, L<Linux::AIO>. 1571L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
1572more natural syntax.
338 1573
339=head1 AUTHOR 1574=head1 AUTHOR
340 1575
341 Marc Lehmann <schmorp@schmorp.de> 1576 Marc Lehmann <schmorp@schmorp.de>
342 http://home.schmorp.de/ 1577 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines