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.116 by root, Wed Oct 3 21:27:51 2007 UTC vs.
Revision 1.258 by root, Thu Jan 21 23:04:46 2016 UTC

4 4
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", IO::AIO::O_RDONLY, 0, sub {
10 my $fh = shift 10 my $fh = shift
11 or die "/etc/passwd: $!"; 11 or die "/etc/passwd: $!";
12 ... 12 ...
13 }; 13 };
14 14
26 $req->cancel; # cancel request if still in queue 26 $req->cancel; # cancel request if still in queue
27 27
28 my $grp = aio_group sub { print "all stats done\n" }; 28 my $grp = aio_group sub { print "all stats done\n" };
29 add $grp aio_stat "..." for ...; 29 add $grp aio_stat "..." for ...;
30 30
31 # AnyEvent integration
32 open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
33 my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
34
35 # Event integration
36 Event->io (fd => IO::AIO::poll_fileno,
37 poll => 'r',
38 cb => \&IO::AIO::poll_cb);
39
40 # Glib/Gtk2 integration
41 add_watch Glib::IO IO::AIO::poll_fileno,
42 in => sub { IO::AIO::poll_cb; 1 };
43
44 # Tk integration
45 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
46 readable => \&IO::AIO::poll_cb);
47
48 # Danga::Socket integration
49 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
50 \&IO::AIO::poll_cb);
51
52=head1 DESCRIPTION 31=head1 DESCRIPTION
53 32
54This module implements asynchronous I/O using whatever means your 33This module implements asynchronous I/O using whatever means your
55operating system supports. 34operating system supports. It is implemented as an interface to C<libeio>
35(L<http://software.schmorp.de/pkg/libeio.html>).
56 36
57Asynchronous means that operations that can normally block your program 37Asynchronous means that operations that can normally block your program
58(e.g. reading from disk) will be done asynchronously: the operation 38(e.g. reading from disk) will be done asynchronously: the operation
59will still block, but you can do something else in the meantime. This 39will still block, but you can do something else in the meantime. This
60is extremely useful for programs that need to stay interactive even 40is extremely useful for programs that need to stay interactive even
64on a RAID volume or over NFS when you do a number of stat operations 44on a RAID volume or over NFS when you do a number of stat operations
65concurrently. 45concurrently.
66 46
67While most of this works on all types of file descriptors (for 47While most of this works on all types of file descriptors (for
68example sockets), using these functions on file descriptors that 48example sockets), using these functions on file descriptors that
69support nonblocking operation (again, sockets, pipes etc.) is very 49support nonblocking operation (again, sockets, pipes etc.) is
70inefficient. Use an event loop for that (such as the L<Event|Event> 50very inefficient. Use an event loop for that (such as the L<EV>
71module): IO::AIO will naturally fit into such an event loop itself. 51module): IO::AIO will naturally fit into such an event loop itself.
72 52
73In this version, a number of threads are started that execute your 53In this version, a number of threads are started that execute your
74requests and signal their completion. You don't need thread support 54requests and signal their completion. You don't need thread support
75in perl, and the threads created by this module will not be visible 55in perl, and the threads created by this module will not be visible
85yourself, always call C<poll_cb> from within the same thread, or never 65yourself, always call C<poll_cb> from within the same thread, or never
86call C<poll_cb> (or other C<aio_> functions) recursively. 66call C<poll_cb> (or other C<aio_> functions) recursively.
87 67
88=head2 EXAMPLE 68=head2 EXAMPLE
89 69
90This is a simple example that uses the Event module and loads 70This is a simple example that uses the EV module and loads
91F</etc/passwd> asynchronously: 71F</etc/passwd> asynchronously:
92 72
93 use Fcntl;
94 use Event; 73 use EV;
95 use IO::AIO; 74 use IO::AIO;
96 75
97 # register the IO::AIO callback with Event 76 # register the IO::AIO callback with EV
98 Event->io (fd => IO::AIO::poll_fileno, 77 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
99 poll => 'r',
100 cb => \&IO::AIO::poll_cb);
101 78
102 # queue the request to open /etc/passwd 79 # queue the request to open /etc/passwd
103 aio_open "/etc/passwd", O_RDONLY, 0, sub { 80 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
104 my $fh = shift 81 my $fh = shift
105 or die "error while opening: $!"; 82 or die "error while opening: $!";
106 83
107 # stat'ing filehandles is generally non-blocking 84 # stat'ing filehandles is generally non-blocking
108 my $size = -s $fh; 85 my $size = -s $fh;
117 94
118 # file contents now in $contents 95 # file contents now in $contents
119 print $contents; 96 print $contents;
120 97
121 # exit event loop and program 98 # exit event loop and program
122 Event::unloop; 99 EV::break;
123 }; 100 };
124 }; 101 };
125 102
126 # possibly queue up other requests, or open GUI windows, 103 # possibly queue up other requests, or open GUI windows,
127 # check for sockets etc. etc. 104 # check for sockets etc. etc.
128 105
129 # process events as long as there are some: 106 # process events as long as there are some:
130 Event::loop; 107 EV::run;
131 108
132=head1 REQUEST ANATOMY AND LIFETIME 109=head1 REQUEST ANATOMY AND LIFETIME
133 110
134Every C<aio_*> function creates a request. which is a C data structure not 111Every C<aio_*> function creates a request. which is a C data structure not
135directly visible to Perl. 112directly visible to Perl.
183 160
184=cut 161=cut
185 162
186package IO::AIO; 163package IO::AIO;
187 164
188no warnings; 165use Carp ();
189use strict 'vars'; 166
167use common::sense;
190 168
191use base 'Exporter'; 169use base 'Exporter';
192 170
193BEGIN { 171BEGIN {
194 our $VERSION = '2.5'; 172 our $VERSION = 4.33;
195 173
196 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat 174 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
197 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink 175 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
198 aio_readlink aio_fsync aio_fdatasync aio_readahead aio_rename aio_link 176 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
177 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_allocate
178 aio_pathsync aio_readahead aio_fiemap
179 aio_rename aio_link aio_move aio_copy aio_group
199 aio_move aio_copy aio_group aio_nop aio_mknod aio_load aio_rmtree aio_mkdir 180 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
200 aio_chown aio_chmod aio_utime aio_truncate); 181 aio_chmod aio_utime aio_truncate
182 aio_msync aio_mtouch aio_mlock aio_mlockall
183 aio_statvfs
184 aio_wd);
185
201 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice aio_block)); 186 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
202 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 187 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
203 min_parallel max_parallel max_idle 188 min_parallel max_parallel max_idle idle_timeout
204 nreqs nready npending nthreads 189 nreqs nready npending nthreads
205 max_poll_time max_poll_reqs); 190 max_poll_time max_poll_reqs
191 sendfile fadvise madvise
192 mmap munmap munlock munlockall);
193
194 push @AIO_REQ, qw(aio_busy); # not exported
206 195
207 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 196 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
208 197
209 require XSLoader; 198 require XSLoader;
210 XSLoader::load ("IO::AIO", $VERSION); 199 XSLoader::load ("IO::AIO", $VERSION);
211} 200}
212 201
213=head1 FUNCTIONS 202=head1 FUNCTIONS
214 203
215=head2 AIO REQUEST FUNCTIONS 204=head2 QUICK OVERVIEW
205
206This section simply lists the prototypes most of the functions for
207quick reference. See the following sections for function-by-function
208documentation.
209
210 aio_wd $pathname, $callback->($wd)
211 aio_open $pathname, $flags, $mode, $callback->($fh)
212 aio_close $fh, $callback->($status)
213 aio_seek $fh,$offset,$whence, $callback->($offs)
214 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
215 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
216 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
217 aio_readahead $fh,$offset,$length, $callback->($retval)
218 aio_stat $fh_or_path, $callback->($status)
219 aio_lstat $fh, $callback->($status)
220 aio_statvfs $fh_or_path, $callback->($statvfs)
221 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
222 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
223 aio_chmod $fh_or_path, $mode, $callback->($status)
224 aio_truncate $fh_or_path, $offset, $callback->($status)
225 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
226 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
227 aio_unlink $pathname, $callback->($status)
228 aio_mknod $pathname, $mode, $dev, $callback->($status)
229 aio_link $srcpath, $dstpath, $callback->($status)
230 aio_symlink $srcpath, $dstpath, $callback->($status)
231 aio_readlink $pathname, $callback->($link)
232 aio_realpath $pathname, $callback->($path)
233 aio_rename $srcpath, $dstpath, $callback->($status)
234 aio_mkdir $pathname, $mode, $callback->($status)
235 aio_rmdir $pathname, $callback->($status)
236 aio_readdir $pathname, $callback->($entries)
237 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
238 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
239 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
240 aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
241 aio_load $pathname, $data, $callback->($status)
242 aio_copy $srcpath, $dstpath, $callback->($status)
243 aio_move $srcpath, $dstpath, $callback->($status)
244 aio_rmtree $pathname, $callback->($status)
245 aio_sync $callback->($status)
246 aio_syncfs $fh, $callback->($status)
247 aio_fsync $fh, $callback->($status)
248 aio_fdatasync $fh, $callback->($status)
249 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
250 aio_pathsync $pathname, $callback->($status)
251 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
252 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
253 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
254 aio_mlockall $flags, $callback->($status)
255 aio_group $callback->(...)
256 aio_nop $callback->()
257
258 $prev_pri = aioreq_pri [$pri]
259 aioreq_nice $pri_adjust
260
261 IO::AIO::poll_wait
262 IO::AIO::poll_cb
263 IO::AIO::poll
264 IO::AIO::flush
265 IO::AIO::max_poll_reqs $nreqs
266 IO::AIO::max_poll_time $seconds
267 IO::AIO::min_parallel $nthreads
268 IO::AIO::max_parallel $nthreads
269 IO::AIO::max_idle $nthreads
270 IO::AIO::idle_timeout $seconds
271 IO::AIO::max_outstanding $maxreqs
272 IO::AIO::nreqs
273 IO::AIO::nready
274 IO::AIO::npending
275
276 IO::AIO::sendfile $ofh, $ifh, $offset, $count
277 IO::AIO::fadvise $fh, $offset, $len, $advice
278 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
279 IO::AIO::munmap $scalar
280 IO::AIO::madvise $scalar, $offset, $length, $advice
281 IO::AIO::mprotect $scalar, $offset, $length, $protect
282 IO::AIO::munlock $scalar, $offset = 0, $length = undef
283 IO::AIO::munlockall
284
285=head2 API NOTES
216 286
217All the C<aio_*> calls are more or less thin wrappers around the syscall 287All the C<aio_*> calls are more or less thin wrappers around the syscall
218with the same name (sans C<aio_>). The arguments are similar or identical, 288with the same name (sans C<aio_>). The arguments are similar or identical,
219and they all accept an additional (and optional) C<$callback> argument 289and they all accept an additional (and optional) C<$callback> argument
220which must be a code reference. This code reference will get called with 290which must be a code reference. This code reference will be called after
221the syscall return code (e.g. most syscalls return C<-1> on error, unlike 291the syscall has been executed in an asynchronous fashion. The results
222perl, which usually delivers "false") as it's sole argument when the given 292of the request will be passed as arguments to the callback (and, if an
223syscall has been executed asynchronously. 293error occured, in C<$!>) - for most requests the syscall return code (e.g.
294most syscalls return C<-1> on error, unlike perl, which usually delivers
295"false").
296
297Some requests (such as C<aio_readdir>) pass the actual results and
298communicate failures by passing C<undef>.
224 299
225All functions expecting a filehandle keep a copy of the filehandle 300All functions expecting a filehandle keep a copy of the filehandle
226internally until the request has finished. 301internally until the request has finished.
227 302
228All functions return request objects of type L<IO::AIO::REQ> that allow 303All functions return request objects of type L<IO::AIO::REQ> that allow
229further manipulation of those requests while they are in-flight. 304further manipulation of those requests while they are in-flight.
230 305
231The pathnames you pass to these routines I<must> be absolute and 306The pathnames you pass to these routines I<should> be absolute. The
232encoded as octets. The reason for the former is that at the time the 307reason for this is that at the time the request is being executed, the
233request is being executed, the current working directory could have 308current working directory could have changed. Alternatively, you can
234changed. Alternatively, you can make sure that you never change the 309make sure that you never change the current working directory anywhere
235current working directory anywhere in the program and then use relative 310in the program and then use relative paths. You can also take advantage
236paths. 311of IO::AIOs working directory abstraction, that lets you specify paths
312relative to some previously-opened "working directory object" - see the
313description of the C<IO::AIO::WD> class later in this document.
237 314
238To encode pathnames as octets, either make sure you either: a) always pass 315To encode pathnames as octets, either make sure you either: a) always pass
239in filenames you got from outside (command line, readdir etc.) without 316in filenames you got from outside (command line, readdir etc.) without
240tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode 317tinkering, b) are in your native filesystem encoding, c) use the Encode
241your pathnames to the locale (or other) encoding in effect in the user 318module and encode your pathnames to the locale (or other) encoding in
242environment, d) use Glib::filename_from_unicode on unicode filenames or e) 319effect in the user environment, d) use Glib::filename_from_unicode on
243use something else to ensure your scalar has the correct contents. 320unicode filenames or e) use something else to ensure your scalar has the
321correct contents.
244 322
245This works, btw. independent of the internal UTF-8 bit, which IO::AIO 323This works, btw. independent of the internal UTF-8 bit, which IO::AIO
246handles correctly wether it is set or not. 324handles correctly whether it is set or not.
325
326=head2 AIO REQUEST FUNCTIONS
247 327
248=over 4 328=over 4
249 329
250=item $prev_pri = aioreq_pri [$pri] 330=item $prev_pri = aioreq_pri [$pri]
251 331
281 361
282 362
283=item aio_open $pathname, $flags, $mode, $callback->($fh) 363=item aio_open $pathname, $flags, $mode, $callback->($fh)
284 364
285Asynchronously open or create a file and call the callback with a newly 365Asynchronously open or create a file and call the callback with a newly
286created filehandle for the file. 366created filehandle for the file (or C<undef> in case of an error).
287 367
288The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 368The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
289for an explanation. 369for an explanation.
290 370
291The C<$flags> argument is a bitmask. See the C<Fcntl> module for a 371The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
298by the umask in effect then the request is being executed, so better never 378by the umask in effect then the request is being executed, so better never
299change the umask. 379change the umask.
300 380
301Example: 381Example:
302 382
303 aio_open "/etc/passwd", O_RDONLY, 0, sub { 383 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
304 if ($_[0]) { 384 if ($_[0]) {
305 print "open successful, fh is $_[0]\n"; 385 print "open successful, fh is $_[0]\n";
306 ... 386 ...
307 } else { 387 } else {
308 die "open failed: $!\n"; 388 die "open failed: $!\n";
309 } 389 }
310 }; 390 };
311 391
392In addition to all the common open modes/flags (C<O_RDONLY>, C<O_WRONLY>,
393C<O_RDWR>, C<O_CREAT>, C<O_TRUNC>, C<O_EXCL> and C<O_APPEND>), the
394following POSIX and non-POSIX constants are available (missing ones on
395your system are, as usual, C<0>):
396
397C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
398C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
399C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, and C<O_TTY_INIT>.
400
312 401
313=item aio_close $fh, $callback->($status) 402=item aio_close $fh, $callback->($status)
314 403
315Asynchronously close a file and call the callback with the result 404Asynchronously close a file and call the callback with the result
316code. 405code.
317 406
318Unlike the other functions operating on files, this function uses the 407Unfortunately, you can't do this to perl. Perl I<insists> very strongly on
319PerlIO layer to close the filehandle. The reason is that the PerlIO API 408closing the file descriptor associated with the filehandle itself.
320insists on closing the underlying fd itself, no matter what, and doesn't
321allow modifications to the fd. Unfortunately, it is not clear that you can
322call PerlIO from different threads (actually, its quite clear that this
323won't work in some cases), so while it likely works perfectly with simple
324file handles (such as the ones created by C<aio_open>) it might fail in
325interesting ways for others.
326 409
327Having said that, aio_close tries to clean up the filehandle as much as 410Therefore, C<aio_close> will not close the filehandle - instead it will
328possible before handing it to an io thread, and generally does work. 411use dup2 to overwrite the file descriptor with the write-end of a pipe
412(the pipe fd will be created on demand and will be cached).
329 413
414Or in other words: the file descriptor will be closed, but it will not be
415free for reuse until the perl filehandle is closed.
416
417=cut
418
419=item aio_seek $fh, $offset, $whence, $callback->($offs)
420
421Seeks the filehandle to the new C<$offset>, similarly to perl's
422C<sysseek>. The C<$whence> can use the traditional values (C<0> for
423C<IO::AIO::SEEK_SET>, C<1> for C<IO::AIO::SEEK_CUR> or C<2> for
424C<IO::AIO::SEEK_END>).
425
426The resulting absolute offset will be passed to the callback, or C<-1> in
427case of an error.
428
429In theory, the C<$whence> constants could be different than the
430corresponding values from L<Fcntl>, but perl guarantees they are the same,
431so don't panic.
432
433As a GNU/Linux (and maybe Solaris) extension, also the constants
434C<IO::AIO::SEEK_DATA> and C<IO::AIO::SEEK_HOLE> are available, if they
435could be found. No guarantees about suitability for use in C<aio_seek> or
436Perl's C<sysseek> can be made though, although I would naively assume they
437"just work".
330 438
331=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 439=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
332 440
333=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 441=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
334 442
335Reads or writes C<$length> bytes from the specified C<$fh> and C<$offset> 443Reads or writes C<$length> bytes from or to the specified C<$fh> and
336into the scalar given by C<$data> and offset C<$dataoffset> and calls the 444C<$offset> into the scalar given by C<$data> and offset C<$dataoffset>
337callback without the actual number of bytes read (or -1 on error, just 445and calls the callback without the actual number of bytes read (or -1 on
338like the syscall). 446error, just like the syscall).
447
448C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to
449offset plus the actual number of bytes read.
339 450
340If C<$offset> is undefined, then the current file descriptor offset will 451If C<$offset> is undefined, then the current file descriptor offset will
341be used (and updated), otherwise the file descriptor offset will not be 452be used (and updated), otherwise the file descriptor offset will not be
342changed by these calls. 453changed by these calls.
343 454
344If C<$length> is undefined in C<aio_write>, use the remaining length of C<$data>. 455If C<$length> is undefined in C<aio_write>, use the remaining length of
456C<$data>.
345 457
346If C<$dataoffset> is less than zero, it will be counted from the end of 458If C<$dataoffset> is less than zero, it will be counted from the end of
347C<$data>. 459C<$data>.
348 460
349The C<$data> scalar I<MUST NOT> be modified in any way while the request 461The C<$data> scalar I<MUST NOT> be modified in any way while the request
363 475
364Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts 476Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
365reading at byte offset C<$in_offset>, and starts writing at the current 477reading at byte offset C<$in_offset>, and starts writing at the current
366file offset of C<$out_fh>. Because of that, it is not safe to issue more 478file offset of C<$out_fh>. Because of that, it is not safe to issue more
367than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each 479than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
368other. 480other. The same C<$in_fh> works fine though, as this function does not
481move or use the file offset of C<$in_fh>.
369 482
483Please note that C<aio_sendfile> can read more bytes from C<$in_fh> than
484are written, and there is no way to find out how many more bytes have been
485read from C<aio_sendfile> alone, as C<aio_sendfile> only provides the
486number of bytes written to C<$out_fh>. Only if the result value equals
487C<$length> one can assume that C<$length> bytes have been read.
488
489Unlike with other C<aio_> functions, it makes a lot of sense to use
490C<aio_sendfile> on non-blocking sockets, as long as one end (typically
491the C<$in_fh>) is a file - the file I/O will then be asynchronous, while
492the socket I/O will be non-blocking. Note, however, that you can run
493into a trap where C<aio_sendfile> reads some data with readahead, then
494fails to write all data, and when the socket is ready the next time, the
495data in the cache is already lost, forcing C<aio_sendfile> to again hit
496the disk. Explicit C<aio_read> + C<aio_write> let's you better control
497resource usage.
498
370This call tries to make use of a native C<sendfile> syscall to provide 499This call tries to make use of a native C<sendfile>-like syscall to
371zero-copy operation. For this to work, C<$out_fh> should refer to a 500provide zero-copy operation. For this to work, C<$out_fh> should refer to
372socket, and C<$in_fh> should refer to mmap'able file. 501a socket, and C<$in_fh> should refer to an mmap'able file.
373 502
374If the native sendfile call fails or is not implemented, it will be 503If a native sendfile cannot be found or it fails with C<ENOSYS>,
375emulated, so you can call C<aio_sendfile> on any type of filehandle 504C<EINVAL>, C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or
505C<ENOTSOCK>, it will be emulated, so you can call C<aio_sendfile> on any
376regardless of the limitations of the operating system. 506type of filehandle regardless of the limitations of the operating system.
377 507
378Please note, however, that C<aio_sendfile> can read more bytes from 508As native sendfile syscalls (as practically any non-POSIX interface hacked
379C<$in_fh> than are written, and there is no way to find out how many 509together in a hurry to improve benchmark numbers) tend to be rather buggy
380bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only 510on many systems, this implementation tries to work around some known bugs
381provides the number of bytes written to C<$out_fh>. Only if the result 511in Linux and FreeBSD kernels (probably others, too), but that might fail,
382value equals C<$length> one can assume that C<$length> bytes have been 512so you really really should check the return value of C<aio_sendfile> -
383read. 513fewre bytes than expected might have been transferred.
384 514
385 515
386=item aio_readahead $fh,$offset,$length, $callback->($retval) 516=item aio_readahead $fh,$offset,$length, $callback->($retval)
387 517
388C<aio_readahead> populates the page cache with data from a file so that 518C<aio_readahead> populates the page cache with data from a file so that
411 541
412Currently, the stats are always 64-bit-stats, i.e. instead of returning an 542Currently, the stats are always 64-bit-stats, i.e. instead of returning an
413error when stat'ing a large file, the results will be silently truncated 543error when stat'ing a large file, the results will be silently truncated
414unless perl itself is compiled with large file support. 544unless perl itself is compiled with large file support.
415 545
546To help interpret the mode and dev/rdev stat values, IO::AIO offers the
547following constants and functions (if not implemented, the constants will
548be C<0> and the functions will either C<croak> or fall back on traditional
549behaviour).
550
551C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
552C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
553C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
554
416Example: Print the length of F</etc/passwd>: 555Example: Print the length of F</etc/passwd>:
417 556
418 aio_stat "/etc/passwd", sub { 557 aio_stat "/etc/passwd", sub {
419 $_[0] and die "stat failed: $!"; 558 $_[0] and die "stat failed: $!";
420 print "size is ", -s _, "\n"; 559 print "size is ", -s _, "\n";
421 }; 560 };
422 561
423 562
563=item aio_statvfs $fh_or_path, $callback->($statvfs)
564
565Works like the POSIX C<statvfs> or C<fstatvfs> syscalls, depending on
566whether a file handle or path was passed.
567
568On success, the callback is passed a hash reference with the following
569members: C<bsize>, C<frsize>, C<blocks>, C<bfree>, C<bavail>, C<files>,
570C<ffree>, C<favail>, C<fsid>, C<flag> and C<namemax>. On failure, C<undef>
571is passed.
572
573The following POSIX IO::AIO::ST_* constants are defined: C<ST_RDONLY> and
574C<ST_NOSUID>.
575
576The following non-POSIX IO::AIO::ST_* flag masks are defined to
577their correct value when available, or to C<0> on systems that do
578not support them: C<ST_NODEV>, C<ST_NOEXEC>, C<ST_SYNCHRONOUS>,
579C<ST_MANDLOCK>, C<ST_WRITE>, C<ST_APPEND>, C<ST_IMMUTABLE>, C<ST_NOATIME>,
580C<ST_NODIRATIME> and C<ST_RELATIME>.
581
582Example: stat C</wd> and dump out the data if successful.
583
584 aio_statvfs "/wd", sub {
585 my $f = $_[0]
586 or die "statvfs: $!";
587
588 use Data::Dumper;
589 say Dumper $f;
590 };
591
592 # result:
593 {
594 bsize => 1024,
595 bfree => 4333064312,
596 blocks => 10253828096,
597 files => 2050765568,
598 flag => 4096,
599 favail => 2042092649,
600 bavail => 4333064312,
601 ffree => 2042092649,
602 namemax => 255,
603 frsize => 1024,
604 fsid => 1810
605 }
606
607Here is a (likely partial - send me updates!) list of fsid values used by
608Linux - it is safe to hardcode these when C<$^O> is C<linux>:
609
610 0x0000adf5 adfs
611 0x0000adff affs
612 0x5346414f afs
613 0x09041934 anon-inode filesystem
614 0x00000187 autofs
615 0x42465331 befs
616 0x1badface bfs
617 0x42494e4d binfmt_misc
618 0x9123683e btrfs
619 0x0027e0eb cgroupfs
620 0xff534d42 cifs
621 0x73757245 coda
622 0x012ff7b7 coh
623 0x28cd3d45 cramfs
624 0x453dcd28 cramfs-wend (wrong endianness)
625 0x64626720 debugfs
626 0x00001373 devfs
627 0x00001cd1 devpts
628 0x0000f15f ecryptfs
629 0x00414a53 efs
630 0x0000137d ext
631 0x0000ef53 ext2/ext3/ext4
632 0x0000ef51 ext2
633 0xf2f52010 f2fs
634 0x00004006 fat
635 0x65735546 fuseblk
636 0x65735543 fusectl
637 0x0bad1dea futexfs
638 0x01161970 gfs2
639 0x47504653 gpfs
640 0x00004244 hfs
641 0xf995e849 hpfs
642 0x00c0ffee hostfs
643 0x958458f6 hugetlbfs
644 0x2bad1dea inotifyfs
645 0x00009660 isofs
646 0x000072b6 jffs2
647 0x3153464a jfs
648 0x6b414653 k-afs
649 0x0bd00bd0 lustre
650 0x0000137f minix
651 0x0000138f minix 30 char names
652 0x00002468 minix v2
653 0x00002478 minix v2 30 char names
654 0x00004d5a minix v3
655 0x19800202 mqueue
656 0x00004d44 msdos
657 0x0000564c novell
658 0x00006969 nfs
659 0x6e667364 nfsd
660 0x00003434 nilfs
661 0x5346544e ntfs
662 0x00009fa1 openprom
663 0x7461636F ocfs2
664 0x00009fa0 proc
665 0x6165676c pstorefs
666 0x0000002f qnx4
667 0x68191122 qnx6
668 0x858458f6 ramfs
669 0x52654973 reiserfs
670 0x00007275 romfs
671 0x67596969 rpc_pipefs
672 0x73636673 securityfs
673 0xf97cff8c selinux
674 0x0000517b smb
675 0x534f434b sockfs
676 0x73717368 squashfs
677 0x62656572 sysfs
678 0x012ff7b6 sysv2
679 0x012ff7b5 sysv4
680 0x01021994 tmpfs
681 0x15013346 udf
682 0x00011954 ufs
683 0x54190100 ufs byteswapped
684 0x00009fa2 usbdevfs
685 0x01021997 v9fs
686 0xa501fcf5 vxfs
687 0xabba1974 xenfs
688 0x012ff7b4 xenix
689 0x58465342 xfs
690 0x012fd16d xia
691
424=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 692=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
425 693
426Works like perl's C<utime> function (including the special case of $atime 694Works like perl's C<utime> function (including the special case of $atime
427and $mtime being undef). Fractional times are supported if the underlying 695and $mtime being undef). Fractional times are supported if the underlying
428syscalls support them. 696syscalls support them.
455=item aio_truncate $fh_or_path, $offset, $callback->($status) 723=item aio_truncate $fh_or_path, $offset, $callback->($status)
456 724
457Works like truncate(2) or ftruncate(2). 725Works like truncate(2) or ftruncate(2).
458 726
459 727
728=item aio_allocate $fh, $mode, $offset, $len, $callback->($status)
729
730Allocates or frees disk space according to the C<$mode> argument. See the
731linux C<fallocate> documentation for details.
732
733C<$mode> is usually C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> to allocate
734space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE>,
735to deallocate a file range.
736
737IO::AIO also supports C<FALLOC_FL_COLLAPSE_RANGE>, to remove a range
738(without leaving a hole) and C<FALLOC_FL_ZERO_RANGE>, to zero a range (see
739your L<fallocate(2)> manpage).
740
741The file system block size used by C<fallocate> is presumably the
742C<f_bsize> returned by C<statvfs>.
743
744If C<fallocate> isn't available or cannot be emulated (currently no
745emulation will be attempted), passes C<-1> and sets C<$!> to C<ENOSYS>.
746
747
460=item aio_chmod $fh_or_path, $mode, $callback->($status) 748=item aio_chmod $fh_or_path, $mode, $callback->($status)
461 749
462Works like perl's C<chmod> function. 750Works like perl's C<chmod> function.
463 751
464 752
466 754
467Asynchronously unlink (delete) a file and call the callback with the 755Asynchronously unlink (delete) a file and call the callback with the
468result code. 756result code.
469 757
470 758
471=item aio_mknod $path, $mode, $dev, $callback->($status) 759=item aio_mknod $pathname, $mode, $dev, $callback->($status)
472 760
473[EXPERIMENTAL] 761[EXPERIMENTAL]
474 762
475Asynchronously create a device node (or fifo). See mknod(2). 763Asynchronously create a device node (or fifo). See mknod(2).
476 764
477The only (POSIX-) portable way of calling this function is: 765The only (POSIX-) portable way of calling this function is:
478 766
479 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 767 aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
480 768
769See C<aio_stat> for info about some potentially helpful extra constants
770and functions.
481 771
482=item aio_link $srcpath, $dstpath, $callback->($status) 772=item aio_link $srcpath, $dstpath, $callback->($status)
483 773
484Asynchronously create a new link to the existing object at C<$srcpath> at 774Asynchronously create a new link to the existing object at C<$srcpath> at
485the path C<$dstpath> and call the callback with the result code. 775the path C<$dstpath> and call the callback with the result code.
489 779
490Asynchronously create a new symbolic link to the existing object at C<$srcpath> at 780Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
491the path C<$dstpath> and call the callback with the result code. 781the path C<$dstpath> and call the callback with the result code.
492 782
493 783
494=item aio_readlink $path, $callback->($link) 784=item aio_readlink $pathname, $callback->($link)
495 785
496Asynchronously read the symlink specified by C<$path> and pass it to 786Asynchronously read the symlink specified by C<$path> and pass it to
497the callback. If an error occurs, nothing or undef gets passed to the 787the callback. If an error occurs, nothing or undef gets passed to the
498callback. 788callback.
499 789
500 790
791=item aio_realpath $pathname, $callback->($path)
792
793Asynchronously make the path absolute and resolve any symlinks in
794C<$path>. The resulting path only consists of directories (same as
795L<Cwd::realpath>).
796
797This request can be used to get the absolute path of the current working
798directory by passing it a path of F<.> (a single dot).
799
800
501=item aio_rename $srcpath, $dstpath, $callback->($status) 801=item aio_rename $srcpath, $dstpath, $callback->($status)
502 802
503Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 803Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
504rename(2) and call the callback with the result code. 804rename(2) and call the callback with the result code.
805
806On systems that support the AIO::WD working directory abstraction
807natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
808of failing, C<rename> is called on the absolute path of C<$wd>.
505 809
506 810
507=item aio_mkdir $pathname, $mode, $callback->($status) 811=item aio_mkdir $pathname, $mode, $callback->($status)
508 812
509Asynchronously mkdir (create) a directory and call the callback with 813Asynchronously mkdir (create) a directory and call the callback with
514=item aio_rmdir $pathname, $callback->($status) 818=item aio_rmdir $pathname, $callback->($status)
515 819
516Asynchronously rmdir (delete) a directory and call the callback with the 820Asynchronously rmdir (delete) a directory and call the callback with the
517result code. 821result code.
518 822
823On systems that support the AIO::WD working directory abstraction
824natively, the case C<[$wd, "."]> is specialcased - instead of failing,
825C<rmdir> is called on the absolute path of C<$wd>.
826
519 827
520=item aio_readdir $pathname, $callback->($entries) 828=item aio_readdir $pathname, $callback->($entries)
521 829
522Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 830Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
523directory (i.e. opendir + readdir + closedir). The entries will not be 831directory (i.e. opendir + readdir + closedir). The entries will not be
524sorted, and will B<NOT> include the C<.> and C<..> entries. 832sorted, and will B<NOT> include the C<.> and C<..> entries.
525 833
526The callback a single argument which is either C<undef> or an array-ref 834The callback is passed a single argument which is either C<undef> or an
527with the filenames. 835array-ref with the filenames.
528 836
529 837
838=item aio_readdirx $pathname, $flags, $callback->($entries, $flags)
839
840Quite similar to C<aio_readdir>, but the C<$flags> argument allows one to
841tune behaviour and output format. In case of an error, C<$entries> will be
842C<undef>.
843
844The flags are a combination of the following constants, ORed together (the
845flags will also be passed to the callback, possibly modified):
846
847=over 4
848
849=item IO::AIO::READDIR_DENTS
850
851When this flag is off, then the callback gets an arrayref consisting of
852names only (as with C<aio_readdir>), otherwise it gets an arrayref with
853C<[$name, $type, $inode]> arrayrefs, each describing a single directory
854entry in more detail.
855
856C<$name> is the name of the entry.
857
858C<$type> is one of the C<IO::AIO::DT_xxx> constants:
859
860C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>,
861C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>,
862C<IO::AIO::DT_WHT>.
863
864C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to
865know, you have to run stat yourself. Also, for speed reasons, the C<$type>
866scalars are read-only: you can not modify them.
867
868C<$inode> is the inode number (which might not be exact on systems with 64
869bit inode numbers and 32 bit perls). This field has unspecified content on
870systems that do not deliver the inode information.
871
872=item IO::AIO::READDIR_DIRS_FIRST
873
874When this flag is set, then the names will be returned in an order where
875likely directories come first, in optimal stat order. This is useful when
876you need to quickly find directories, or you want to find all directories
877while avoiding to stat() each entry.
878
879If the system returns type information in readdir, then this is used
880to find directories directly. Otherwise, likely directories are names
881beginning with ".", or otherwise names with no dots, of which names with
882short names are tried first.
883
884=item IO::AIO::READDIR_STAT_ORDER
885
886When this flag is set, then the names will be returned in an order
887suitable for stat()'ing each one. That is, when you plan to stat()
888all files in the given directory, then the returned order will likely
889be fastest.
890
891If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, then
892the likely dirs come first, resulting in a less optimal stat order.
893
894=item IO::AIO::READDIR_FOUND_UNKNOWN
895
896This flag should not be set when calling C<aio_readdirx>. Instead, it
897is being set by C<aio_readdirx>, when any of the C<$type>'s found were
898C<IO::AIO::DT_UNKNOWN>. The absence of this flag therefore indicates that all
899C<$type>'s are known, which can be used to speed up some algorithms.
900
901=back
902
903
530=item aio_load $path, $data, $callback->($status) 904=item aio_load $pathname, $data, $callback->($status)
531 905
532This is a composite request that tries to fully load the given file into 906This is a composite request that tries to fully load the given file into
533memory. Status is the same as with aio_read. 907memory. Status is the same as with aio_read.
534 908
535=cut 909=cut
536 910
537sub aio_load($$;$) { 911sub aio_load($$;$) {
538 aio_block {
539 my ($path, undef, $cb) = @_; 912 my ($path, undef, $cb) = @_;
540 my $data = \$_[1]; 913 my $data = \$_[1];
541 914
542 my $pri = aioreq_pri; 915 my $pri = aioreq_pri;
543 my $grp = aio_group $cb; 916 my $grp = aio_group $cb;
917
918 aioreq_pri $pri;
919 add $grp aio_open $path, O_RDONLY, 0, sub {
920 my $fh = shift
921 or return $grp->result (-1);
544 922
545 aioreq_pri $pri; 923 aioreq_pri $pri;
546 add $grp aio_open $path, O_RDONLY, 0, sub {
547 my $fh = shift
548 or return $grp->result (-1);
549
550 aioreq_pri $pri;
551 add $grp aio_read $fh, 0, (-s $fh), $$data, 0, sub { 924 add $grp aio_read $fh, 0, (-s $fh), $$data, 0, sub {
552 $grp->result ($_[0]); 925 $grp->result ($_[0]);
553 };
554 }; 926 };
555
556 $grp
557 } 927 };
928
929 $grp
558} 930}
559 931
560=item aio_copy $srcpath, $dstpath, $callback->($status) 932=item aio_copy $srcpath, $dstpath, $callback->($status)
561 933
562Try to copy the I<file> (directories not supported as either source or 934Try to copy the I<file> (directories not supported as either source or
563destination) from C<$srcpath> to C<$dstpath> and call the callback with 935destination) from C<$srcpath> to C<$dstpath> and call the callback with
564the C<0> (error) or C<-1> ok. 936a status of C<0> (ok) or C<-1> (error, see C<$!>).
565 937
566This is a composite request that it creates the destination file with 938This is a composite request that creates the destination file with
567mode 0200 and copies the contents of the source file into it using 939mode 0200 and copies the contents of the source file into it using
568C<aio_sendfile>, followed by restoring atime, mtime, access mode and 940C<aio_sendfile>, followed by restoring atime, mtime, access mode and
569uid/gid, in that order. 941uid/gid, in that order.
570 942
571If an error occurs, the partial destination file will be unlinked, if 943If an error occurs, the partial destination file will be unlinked, if
573errors are being ignored. 945errors are being ignored.
574 946
575=cut 947=cut
576 948
577sub aio_copy($$;$) { 949sub aio_copy($$;$) {
578 aio_block {
579 my ($src, $dst, $cb) = @_; 950 my ($src, $dst, $cb) = @_;
580 951
581 my $pri = aioreq_pri; 952 my $pri = aioreq_pri;
582 my $grp = aio_group $cb; 953 my $grp = aio_group $cb;
583 954
584 aioreq_pri $pri; 955 aioreq_pri $pri;
585 add $grp aio_open $src, O_RDONLY, 0, sub { 956 add $grp aio_open $src, O_RDONLY, 0, sub {
586 if (my $src_fh = $_[0]) { 957 if (my $src_fh = $_[0]) {
587 my @stat = stat $src_fh; 958 my @stat = stat $src_fh; # hmm, might block over nfs?
588 959
589 aioreq_pri $pri; 960 aioreq_pri $pri;
590 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub { 961 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
591 if (my $dst_fh = $_[0]) { 962 if (my $dst_fh = $_[0]) {
592 aioreq_pri $pri; 963 aioreq_pri $pri;
593 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub { 964 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
594 if ($_[0] == $stat[7]) { 965 if ($_[0] == $stat[7]) {
595 $grp->result (0); 966 $grp->result (0);
596 close $src_fh; 967 close $src_fh;
597 968
598 # those should not normally block. should. should.
599 utime $stat[8], $stat[9], $dst;
600 chmod $stat[2] & 07777, $dst_fh;
601 chown $stat[4], $stat[5], $dst_fh;
602 close $dst_fh;
603 } else { 969 my $ch = sub {
604 $grp->result (-1);
605 close $src_fh;
606 close $dst_fh;
607
608 aioreq $pri; 970 aioreq_pri $pri;
971 add $grp aio_chmod $dst_fh, $stat[2] & 07777, sub {
972 aioreq_pri $pri;
973 add $grp aio_chown $dst_fh, $stat[4], $stat[5], sub {
974 aioreq_pri $pri;
609 add $grp aio_unlink $dst; 975 add $grp aio_close $dst_fh;
976 }
977 };
610 } 978 };
979
980 aioreq_pri $pri;
981 add $grp aio_utime $dst_fh, $stat[8], $stat[9], sub {
982 if ($_[0] < 0 && $! == ENOSYS) {
983 aioreq_pri $pri;
984 add $grp aio_utime $dst, $stat[8], $stat[9], $ch;
985 } else {
986 $ch->();
987 }
988 };
989 } else {
990 $grp->result (-1);
991 close $src_fh;
992 close $dst_fh;
993
994 aioreq $pri;
995 add $grp aio_unlink $dst;
611 }; 996 }
612 } else {
613 $grp->result (-1);
614 } 997 };
998 } else {
999 $grp->result (-1);
615 }, 1000 }
616
617 } else {
618 $grp->result (-1);
619 } 1001 },
1002
1003 } else {
1004 $grp->result (-1);
620 }; 1005 }
621
622 $grp
623 } 1006 };
1007
1008 $grp
624} 1009}
625 1010
626=item aio_move $srcpath, $dstpath, $callback->($status) 1011=item aio_move $srcpath, $dstpath, $callback->($status)
627 1012
628Try to move the I<file> (directories not supported as either source or 1013Try to move the I<file> (directories not supported as either source or
629destination) from C<$srcpath> to C<$dstpath> and call the callback with 1014destination) from C<$srcpath> to C<$dstpath> and call the callback with
630the C<0> (error) or C<-1> ok. 1015a status of C<0> (ok) or C<-1> (error, see C<$!>).
631 1016
632This is a composite request that tries to rename(2) the file first. If 1017This is a composite request that tries to rename(2) the file first; if
633rename files with C<EXDEV>, it copies the file with C<aio_copy> and, if 1018rename fails with C<EXDEV>, it copies the file with C<aio_copy> and, if
634that is successful, unlinking the C<$srcpath>. 1019that is successful, unlinks the C<$srcpath>.
635 1020
636=cut 1021=cut
637 1022
638sub aio_move($$;$) { 1023sub aio_move($$;$) {
639 aio_block {
640 my ($src, $dst, $cb) = @_; 1024 my ($src, $dst, $cb) = @_;
641 1025
642 my $pri = aioreq_pri; 1026 my $pri = aioreq_pri;
643 my $grp = aio_group $cb; 1027 my $grp = aio_group $cb;
644 1028
645 aioreq_pri $pri; 1029 aioreq_pri $pri;
646 add $grp aio_rename $src, $dst, sub { 1030 add $grp aio_rename $src, $dst, sub {
647 if ($_[0] && $! == EXDEV) { 1031 if ($_[0] && $! == EXDEV) {
648 aioreq_pri $pri; 1032 aioreq_pri $pri;
649 add $grp aio_copy $src, $dst, sub { 1033 add $grp aio_copy $src, $dst, sub {
650 $grp->result ($_[0]);
651
652 if (!$_[0]) {
653 aioreq_pri $pri;
654 add $grp aio_unlink $src;
655 }
656 };
657 } else {
658 $grp->result ($_[0]); 1034 $grp->result ($_[0]);
1035
1036 unless ($_[0]) {
1037 aioreq_pri $pri;
1038 add $grp aio_unlink $src;
1039 }
659 } 1040 };
1041 } else {
1042 $grp->result ($_[0]);
660 }; 1043 }
661
662 $grp
663 } 1044 };
1045
1046 $grp
664} 1047}
665 1048
666=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 1049=item aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
667 1050
668Scans a directory (similar to C<aio_readdir>) but additionally tries to 1051Scans a directory (similar to C<aio_readdir>) but additionally tries to
669efficiently separate the entries of directory C<$path> into two sets of 1052efficiently separate the entries of directory C<$path> into two sets of
670names, directories you can recurse into (directories), and ones you cannot 1053names, directories you can recurse into (directories), and ones you cannot
671recurse into (everything else, including symlinks to directories). 1054recurse into (everything else, including symlinks to directories).
688 1071
689Implementation notes. 1072Implementation notes.
690 1073
691The C<aio_readdir> cannot be avoided, but C<stat()>'ing every entry can. 1074The C<aio_readdir> cannot be avoided, but C<stat()>'ing every entry can.
692 1075
1076If readdir returns file type information, then this is used directly to
1077find directories.
1078
693After reading the directory, the modification time, size etc. of the 1079Otherwise, after reading the directory, the modification time, size etc.
694directory before and after the readdir is checked, and if they match (and 1080of the directory before and after the readdir is checked, and if they
695isn't the current time), the link count will be used to decide how many 1081match (and isn't the current time), the link count will be used to decide
696entries are directories (if >= 2). Otherwise, no knowledge of the number 1082how many entries are directories (if >= 2). Otherwise, no knowledge of the
697of subdirectories will be assumed. 1083number of subdirectories will be assumed.
698 1084
699Then entries will be sorted into likely directories (everything without 1085Then entries will be sorted into likely directories a non-initial dot
700a non-initial dot currently) and likely non-directories (everything 1086currently) and likely non-directories (see C<aio_readdirx>). Then every
701else). Then every entry plus an appended C</.> will be C<stat>'ed, 1087entry plus an appended C</.> will be C<stat>'ed, likely directories first,
702likely directories first. If that succeeds, it assumes that the entry 1088in order of their inode numbers. If that succeeds, it assumes that the
703is a directory or a symlink to directory (which will be checked 1089entry is a directory or a symlink to directory (which will be checked
704seperately). This is often faster than stat'ing the entry itself because 1090separately). This is often faster than stat'ing the entry itself because
705filesystems might detect the type of the entry without reading the inode 1091filesystems might detect the type of the entry without reading the inode
706data (e.g. ext2fs filetype feature). 1092data (e.g. ext2fs filetype feature), even on systems that cannot return
1093the filetype information on readdir.
707 1094
708If the known number of directories (link count - 2) has been reached, the 1095If the known number of directories (link count - 2) has been reached, the
709rest of the entries is assumed to be non-directories. 1096rest of the entries is assumed to be non-directories.
710 1097
711This only works with certainty on POSIX (= UNIX) filesystems, which 1098This only works with certainty on POSIX (= UNIX) filesystems, which
716directory counting heuristic. 1103directory counting heuristic.
717 1104
718=cut 1105=cut
719 1106
720sub aio_scandir($$;$) { 1107sub aio_scandir($$;$) {
721 aio_block {
722 my ($path, $maxreq, $cb) = @_; 1108 my ($path, $maxreq, $cb) = @_;
723 1109
724 my $pri = aioreq_pri; 1110 my $pri = aioreq_pri;
725 1111
726 my $grp = aio_group $cb; 1112 my $grp = aio_group $cb;
727 1113
728 $maxreq = 4 if $maxreq <= 0; 1114 $maxreq = 4 if $maxreq <= 0;
1115
1116 # get a wd object
1117 aioreq_pri $pri;
1118 add $grp aio_wd $path, sub {
1119 $_[0]
1120 or return $grp->result ();
1121
1122 my $wd = [shift, "."];
729 1123
730 # stat once 1124 # stat once
731 aioreq_pri $pri; 1125 aioreq_pri $pri;
732 add $grp aio_stat $path, sub { 1126 add $grp aio_stat $wd, sub {
733 return $grp->result () if $_[0]; 1127 return $grp->result () if $_[0];
734 my $now = time; 1128 my $now = time;
735 my $hash1 = join ":", (stat _)[0,1,3,7,9]; 1129 my $hash1 = join ":", (stat _)[0,1,3,7,9];
736 1130
737 # read the directory entries 1131 # read the directory entries
738 aioreq_pri $pri; 1132 aioreq_pri $pri;
739 add $grp aio_readdir $path, sub { 1133 add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {
740 my $entries = shift 1134 my $entries = shift
741 or return $grp->result (); 1135 or return $grp->result ();
742 1136
743 # stat the dir another time 1137 # stat the dir another time
744 aioreq_pri $pri; 1138 aioreq_pri $pri;
745 add $grp aio_stat $path, sub { 1139 add $grp aio_stat $wd, sub {
746 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 1140 my $hash2 = join ":", (stat _)[0,1,3,7,9];
747 1141
748 my $ndirs; 1142 my $ndirs;
749 1143
750 # take the slow route if anything looks fishy 1144 # take the slow route if anything looks fishy
751 if ($hash1 ne $hash2 or (stat _)[9] == $now) { 1145 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
752 $ndirs = -1; 1146 $ndirs = -1;
753 } else { 1147 } else {
754 # if nlink == 2, we are finished 1148 # if nlink == 2, we are finished
755 # on non-posix-fs's, we rely on nlink < 2 1149 # for non-posix-fs's, we rely on nlink < 2
756 $ndirs = (stat _)[3] - 2 1150 $ndirs = (stat _)[3] - 2
757 or return $grp->result ([], $entries); 1151 or return $grp->result ([], $entries);
758 } 1152 }
759 1153
760 # sort into likely dirs and likely nondirs
761 # dirs == files without ".", short entries first
762 $entries = [map $_->[0],
763 sort { $b->[1] cmp $a->[1] }
764 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
765 @$entries];
766
767 my (@dirs, @nondirs); 1154 my (@dirs, @nondirs);
768 1155
769 my $statgrp = add $grp aio_group sub { 1156 my $statgrp = add $grp aio_group sub {
770 $grp->result (\@dirs, \@nondirs); 1157 $grp->result (\@dirs, \@nondirs);
771 }; 1158 };
772 1159
773 limit $statgrp $maxreq; 1160 limit $statgrp $maxreq;
774 feed $statgrp sub { 1161 feed $statgrp sub {
775 return unless @$entries; 1162 return unless @$entries;
776 my $entry = pop @$entries; 1163 my $entry = shift @$entries;
777 1164
778 aioreq_pri $pri; 1165 aioreq_pri $pri;
1166 $wd->[1] = "$entry/.";
779 add $statgrp aio_stat "$path/$entry/.", sub { 1167 add $statgrp aio_stat $wd, sub {
780 if ($_[0] < 0) { 1168 if ($_[0] < 0) {
781 push @nondirs, $entry; 1169 push @nondirs, $entry;
782 } else { 1170 } else {
783 # need to check for real directory 1171 # need to check for real directory
784 aioreq_pri $pri; 1172 aioreq_pri $pri;
1173 $wd->[1] = $entry;
785 add $statgrp aio_lstat "$path/$entry", sub { 1174 add $statgrp aio_lstat $wd, sub {
786 if (-d _) { 1175 if (-d _) {
787 push @dirs, $entry; 1176 push @dirs, $entry;
788 1177
789 unless (--$ndirs) { 1178 unless (--$ndirs) {
790 push @nondirs, @$entries; 1179 push @nondirs, @$entries;
798 }; 1187 };
799 }; 1188 };
800 }; 1189 };
801 }; 1190 };
802 }; 1191 };
803
804 $grp
805 } 1192 };
1193
1194 $grp
806} 1195}
807 1196
808=item aio_rmtree $path, $callback->($status) 1197=item aio_rmtree $pathname, $callback->($status)
809 1198
810Delete a directory tree starting (and including) C<$path>, return the 1199Delete a directory tree starting (and including) C<$path>, return the
811status of the final C<rmdir> only. This is a composite request that 1200status of the final C<rmdir> only. This is a composite request that
812uses C<aio_scandir> to recurse into and rmdir directories, and unlink 1201uses C<aio_scandir> to recurse into and rmdir directories, and unlink
813everything else. 1202everything else.
814 1203
815=cut 1204=cut
816 1205
817sub aio_rmtree; 1206sub aio_rmtree;
818sub aio_rmtree($;$) { 1207sub aio_rmtree($;$) {
819 aio_block {
820 my ($path, $cb) = @_; 1208 my ($path, $cb) = @_;
821 1209
822 my $pri = aioreq_pri; 1210 my $pri = aioreq_pri;
823 my $grp = aio_group $cb; 1211 my $grp = aio_group $cb;
824 1212
825 aioreq_pri $pri; 1213 aioreq_pri $pri;
826 add $grp aio_scandir $path, 0, sub { 1214 add $grp aio_scandir $path, 0, sub {
827 my ($dirs, $nondirs) = @_; 1215 my ($dirs, $nondirs) = @_;
828 1216
829 my $dirgrp = aio_group sub { 1217 my $dirgrp = aio_group sub {
830 add $grp aio_rmdir $path, sub { 1218 add $grp aio_rmdir $path, sub {
831 $grp->result ($_[0]); 1219 $grp->result ($_[0]);
832 };
833 }; 1220 };
834
835 (aioreq_pri $pri), add $dirgrp aio_rmtree "$path/$_" for @$dirs;
836 (aioreq_pri $pri), add $dirgrp aio_unlink "$path/$_" for @$nondirs;
837
838 add $grp $dirgrp;
839 }; 1221 };
840 1222
841 $grp 1223 (aioreq_pri $pri), add $dirgrp aio_rmtree "$path/$_" for @$dirs;
1224 (aioreq_pri $pri), add $dirgrp aio_unlink "$path/$_" for @$nondirs;
1225
1226 add $grp $dirgrp;
842 } 1227 };
1228
1229 $grp
843} 1230}
1231
1232=item aio_sync $callback->($status)
1233
1234Asynchronously call sync and call the callback when finished.
844 1235
845=item aio_fsync $fh, $callback->($status) 1236=item aio_fsync $fh, $callback->($status)
846 1237
847Asynchronously call fsync on the given filehandle and call the callback 1238Asynchronously call fsync on the given filehandle and call the callback
848with the fsync result code. 1239with the fsync result code.
852Asynchronously call fdatasync on the given filehandle and call the 1243Asynchronously call fdatasync on the given filehandle and call the
853callback with the fdatasync result code. 1244callback with the fdatasync result code.
854 1245
855If this call isn't available because your OS lacks it or it couldn't be 1246If this call isn't available because your OS lacks it or it couldn't be
856detected, it will be emulated by calling C<fsync> instead. 1247detected, it will be emulated by calling C<fsync> instead.
1248
1249=item aio_syncfs $fh, $callback->($status)
1250
1251Asynchronously call the syncfs syscall to sync the filesystem associated
1252to the given filehandle and call the callback with the syncfs result
1253code. If syncfs is not available, calls sync(), but returns C<-1> and sets
1254errno to C<ENOSYS> nevertheless.
1255
1256=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
1257
1258Sync the data portion of the file specified by C<$offset> and C<$length>
1259to disk (but NOT the metadata), by calling the Linux-specific
1260sync_file_range call. If sync_file_range is not available or it returns
1261ENOSYS, then fdatasync or fsync is being substituted.
1262
1263C<$flags> can be a combination of C<IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE>,
1264C<IO::AIO::SYNC_FILE_RANGE_WRITE> and
1265C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range
1266manpage for details.
1267
1268=item aio_pathsync $pathname, $callback->($status)
1269
1270This request tries to open, fsync and close the given path. This is a
1271composite request intended to sync directories after directory operations
1272(E.g. rename). This might not work on all operating systems or have any
1273specific effect, but usually it makes sure that directory changes get
1274written to disc. It works for anything that can be opened for read-only,
1275not just directories.
1276
1277Future versions of this function might fall back to other methods when
1278C<fsync> on the directory fails (such as calling C<sync>).
1279
1280Passes C<0> when everything went ok, and C<-1> on error.
1281
1282=cut
1283
1284sub aio_pathsync($;$) {
1285 my ($path, $cb) = @_;
1286
1287 my $pri = aioreq_pri;
1288 my $grp = aio_group $cb;
1289
1290 aioreq_pri $pri;
1291 add $grp aio_open $path, O_RDONLY, 0, sub {
1292 my ($fh) = @_;
1293 if ($fh) {
1294 aioreq_pri $pri;
1295 add $grp aio_fsync $fh, sub {
1296 $grp->result ($_[0]);
1297
1298 aioreq_pri $pri;
1299 add $grp aio_close $fh;
1300 };
1301 } else {
1302 $grp->result (-1);
1303 }
1304 };
1305
1306 $grp
1307}
1308
1309=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1310
1311This is a rather advanced IO::AIO call, which only works on mmap(2)ed
1312scalars (see the C<IO::AIO::mmap> function, although it also works on data
1313scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the
1314scalar must only be modified in-place while an aio operation is pending on
1315it).
1316
1317It calls the C<msync> function of your OS, if available, with the memory
1318area starting at C<$offset> in the string and ending C<$length> bytes
1319later. If C<$length> is negative, counts from the end, and if C<$length>
1320is C<undef>, then it goes till the end of the string. The flags can be
1321a combination of C<IO::AIO::MS_ASYNC>, C<IO::AIO::MS_INVALIDATE> and
1322C<IO::AIO::MS_SYNC>.
1323
1324=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1325
1326This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1327scalars.
1328
1329It touches (reads or writes) all memory pages in the specified
1330range inside the scalar. All caveats and parameters are the same
1331as for C<aio_msync>, above, except for flags, which must be either
1332C<0> (which reads all pages and ensures they are instantiated) or
1333C<IO::AIO::MT_MODIFY>, which modifies the memory pages (by reading and
1334writing an octet from it, which dirties the page).
1335
1336=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1337
1338This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1339scalars.
1340
1341It reads in all the pages of the underlying storage into memory (if any)
1342and locks them, so they are not getting swapped/paged out or removed.
1343
1344If C<$length> is undefined, then the scalar will be locked till the end.
1345
1346On systems that do not implement C<mlock>, this function returns C<-1>
1347and sets errno to C<ENOSYS>.
1348
1349Note that the corresponding C<munlock> is synchronous and is
1350documented under L<MISCELLANEOUS FUNCTIONS>.
1351
1352Example: open a file, mmap and mlock it - both will be undone when
1353C<$data> gets destroyed.
1354
1355 open my $fh, "<", $path or die "$path: $!";
1356 my $data;
1357 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1358 aio_mlock $data; # mlock in background
1359
1360=item aio_mlockall $flags, $callback->($status)
1361
1362Calls the C<mlockall> function with the given C<$flags> (a combination of
1363C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
1364
1365On systems that do not implement C<mlockall>, this function returns C<-1>
1366and sets errno to C<ENOSYS>.
1367
1368Note that the corresponding C<munlockall> is synchronous and is
1369documented under L<MISCELLANEOUS FUNCTIONS>.
1370
1371Example: asynchronously lock all current and future pages into memory.
1372
1373 aio_mlockall IO::AIO::MCL_FUTURE;
1374
1375=item aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1376
1377Queries the extents of the given file (by calling the Linux C<FIEMAP>
1378ioctl, see L<http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for details). If
1379the ioctl is not available on your OS, then this request will fail with
1380C<ENOSYS>.
1381
1382C<$start> is the starting offset to query extents for, C<$length> is the
1383size of the range to query - if it is C<undef>, then the whole file will
1384be queried.
1385
1386C<$flags> is a combination of flags (C<IO::AIO::FIEMAP_FLAG_SYNC> or
1387C<IO::AIO::FIEMAP_FLAG_XATTR> - C<IO::AIO::FIEMAP_FLAGS_COMPAT> is also
1388exported), and is normally C<0> or C<IO::AIO::FIEMAP_FLAG_SYNC> to query
1389the data portion.
1390
1391C<$count> is the maximum number of extent records to return. If it is
1392C<undef>, then IO::AIO queries all extents of the range. As a very special
1393case, if it is C<0>, then the callback receives the number of extents
1394instead of the extents themselves (which is unreliable, see below).
1395
1396If an error occurs, the callback receives no arguments. The special
1397C<errno> value C<IO::AIO::EBADR> is available to test for flag errors.
1398
1399Otherwise, the callback receives an array reference with extent
1400structures. Each extent structure is an array reference itself, with the
1401following members:
1402
1403 [$logical, $physical, $length, $flags]
1404
1405Flags is any combination of the following flag values (typically either C<0>
1406or C<IO::AIO::FIEMAP_EXTENT_LAST> (1)):
1407
1408C<IO::AIO::FIEMAP_EXTENT_LAST>, C<IO::AIO::FIEMAP_EXTENT_UNKNOWN>,
1409C<IO::AIO::FIEMAP_EXTENT_DELALLOC>, C<IO::AIO::FIEMAP_EXTENT_ENCODED>,
1410C<IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED>, C<IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED>,
1411C<IO::AIO::FIEMAP_EXTENT_DATA_INLINE>, C<IO::AIO::FIEMAP_EXTENT_DATA_TAIL>,
1412C<IO::AIO::FIEMAP_EXTENT_UNWRITTEN>, C<IO::AIO::FIEMAP_EXTENT_MERGED> or
1413C<IO::AIO::FIEMAP_EXTENT_SHARED>.
1414
1415At the time of this writing (Linux 3.2), this requets is unreliable unless
1416C<$count> is C<undef>, as the kernel has all sorts of bugs preventing
1417it to return all extents of a range for files with large number of
1418extents. The code works around all these issues if C<$count> is undef.
857 1419
858=item aio_group $callback->(...) 1420=item aio_group $callback->(...)
859 1421
860This is a very special aio request: Instead of doing something, it is a 1422This is a very special aio request: Instead of doing something, it is a
861container for other aio requests, which is useful if you want to bundle 1423container for other aio requests, which is useful if you want to bundle
899immense (it blocks a thread for a long time) so do not use this function 1461immense (it blocks a thread for a long time) so do not use this function
900except to put your application under artificial I/O pressure. 1462except to put your application under artificial I/O pressure.
901 1463
902=back 1464=back
903 1465
1466
1467=head2 IO::AIO::WD - multiple working directories
1468
1469Your process only has one current working directory, which is used by all
1470threads. This makes it hard to use relative paths (some other component
1471could call C<chdir> at any time, and it is hard to control when the path
1472will be used by IO::AIO).
1473
1474One solution for this is to always use absolute paths. This usually works,
1475but can be quite slow (the kernel has to walk the whole path on every
1476access), and can also be a hassle to implement.
1477
1478Newer POSIX systems have a number of functions (openat, fdopendir,
1479futimensat and so on) that make it possible to specify working directories
1480per operation.
1481
1482For portability, and because the clowns who "designed", or shall I write,
1483perpetrated this new interface were obviously half-drunk, this abstraction
1484cannot be perfect, though.
1485
1486IO::AIO allows you to convert directory paths into a so-called IO::AIO::WD
1487object. This object stores the canonicalised, absolute version of the
1488path, and on systems that allow it, also a directory file descriptor.
1489
1490Everywhere where a pathname is accepted by IO::AIO (e.g. in C<aio_stat>
1491or C<aio_unlink>), one can specify an array reference with an IO::AIO::WD
1492object and a pathname instead (or the IO::AIO::WD object alone, which
1493gets interpreted as C<[$wd, "."]>). If the pathname is absolute, the
1494IO::AIO::WD object is ignored, otherwise the pathname is resolved relative
1495to that IO::AIO::WD object.
1496
1497For example, to get a wd object for F</etc> and then stat F<passwd>
1498inside, you would write:
1499
1500 aio_wd "/etc", sub {
1501 my $etcdir = shift;
1502
1503 # although $etcdir can be undef on error, there is generally no reason
1504 # to check for errors here, as aio_stat will fail with ENOENT
1505 # when $etcdir is undef.
1506
1507 aio_stat [$etcdir, "passwd"], sub {
1508 # yay
1509 };
1510 };
1511
1512The fact that C<aio_wd> is a request and not a normal function shows that
1513creating an IO::AIO::WD object is itself a potentially blocking operation,
1514which is why it is done asynchronously.
1515
1516To stat the directory obtained with C<aio_wd> above, one could write
1517either of the following three request calls:
1518
1519 aio_lstat "/etc" , sub { ... # pathname as normal string
1520 aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
1521 aio_lstat $wd , sub { ... # shorthand for the previous
1522
1523As with normal pathnames, IO::AIO keeps a copy of the working directory
1524object and the pathname string, so you could write the following without
1525causing any issues due to C<$path> getting reused:
1526
1527 my $path = [$wd, undef];
1528
1529 for my $name (qw(abc def ghi)) {
1530 $path->[1] = $name;
1531 aio_stat $path, sub {
1532 # ...
1533 };
1534 }
1535
1536There are some caveats: when directories get renamed (or deleted), the
1537pathname string doesn't change, so will point to the new directory (or
1538nowhere at all), while the directory fd, if available on the system,
1539will still point to the original directory. Most functions accepting a
1540pathname will use the directory fd on newer systems, and the string on
1541older systems. Some functions (such as realpath) will always rely on the
1542string form of the pathname.
1543
1544So this functionality is mainly useful to get some protection against
1545C<chdir>, to easily get an absolute path out of a relative path for future
1546reference, and to speed up doing many operations in the same directory
1547(e.g. when stat'ing all files in a directory).
1548
1549The following functions implement this working directory abstraction:
1550
1551=over 4
1552
1553=item aio_wd $pathname, $callback->($wd)
1554
1555Asynchonously canonicalise the given pathname and convert it to an
1556IO::AIO::WD object representing it. If possible and supported on the
1557system, also open a directory fd to speed up pathname resolution relative
1558to this working directory.
1559
1560If something goes wrong, then C<undef> is passwd to the callback instead
1561of a working directory object and C<$!> is set appropriately. Since
1562passing C<undef> as working directory component of a pathname fails the
1563request with C<ENOENT>, there is often no need for error checking in the
1564C<aio_wd> callback, as future requests using the value will fail in the
1565expected way.
1566
1567=item IO::AIO::CWD
1568
1569This is a compiletime constant (object) that represents the process
1570current working directory.
1571
1572Specifying this object as working directory object for a pathname is as if
1573the pathname would be specified directly, without a directory object. For
1574example, these calls are functionally identical:
1575
1576 aio_stat "somefile", sub { ... };
1577 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1578
1579=back
1580
1581To recover the path associated with an IO::AIO::WD object, you can use
1582C<aio_realpath>:
1583
1584 aio_realpath $wd, sub {
1585 warn "path is $_[0]\n";
1586 };
1587
1588Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
1589sometimes, fall back to using an absolue path.
1590
904=head2 IO::AIO::REQ CLASS 1591=head2 IO::AIO::REQ CLASS
905 1592
906All non-aggregate C<aio_*> functions return an object of this class when 1593All non-aggregate C<aio_*> functions return an object of this class when
907called in non-void context. 1594called in non-void context.
908 1595
911=item cancel $req 1598=item cancel $req
912 1599
913Cancels the request, if possible. Has the effect of skipping execution 1600Cancels the request, if possible. Has the effect of skipping execution
914when entering the B<execute> state and skipping calling the callback when 1601when entering the B<execute> state and skipping calling the callback when
915entering the the B<result> state, but will leave the request otherwise 1602entering the the B<result> state, but will leave the request otherwise
916untouched. That means that requests that currently execute will not be 1603untouched (with the exception of readdir). That means that requests that
917stopped and resources held by the request will not be freed prematurely. 1604currently execute will not be stopped and resources held by the request
1605will not be freed prematurely.
918 1606
919=item cb $req $callback->(...) 1607=item cb $req $callback->(...)
920 1608
921Replace (or simply set) the callback registered to the request. 1609Replace (or simply set) the callback registered to the request.
922 1610
973Their lifetime, simplified, looks like this: when they are empty, they 1661Their lifetime, simplified, looks like this: when they are empty, they
974will finish very quickly. If they contain only requests that are in the 1662will finish very quickly. If they contain only requests that are in the
975C<done> state, they will also finish. Otherwise they will continue to 1663C<done> state, they will also finish. Otherwise they will continue to
976exist. 1664exist.
977 1665
978That means after creating a group you have some time to add requests. And 1666That means after creating a group you have some time to add requests
979in the callbacks of those requests, you can add further requests to the 1667(precisely before the callback has been invoked, which is only done within
980group. And only when all those requests have finished will the the group 1668the C<poll_cb>). And in the callbacks of those requests, you can add
981itself finish. 1669further requests to the group. And only when all those requests have
1670finished will the the group itself finish.
982 1671
983=over 4 1672=over 4
984 1673
985=item add $grp ... 1674=item add $grp ...
986 1675
995=item $grp->cancel_subs 1684=item $grp->cancel_subs
996 1685
997Cancel all subrequests and clears any feeder, but not the group request 1686Cancel all subrequests and clears any feeder, but not the group request
998itself. Useful when you queued a lot of events but got a result early. 1687itself. Useful when you queued a lot of events but got a result early.
999 1688
1689The group request will finish normally (you cannot add requests to the
1690group).
1691
1000=item $grp->result (...) 1692=item $grp->result (...)
1001 1693
1002Set the result value(s) that will be passed to the group callback when all 1694Set the result value(s) that will be passed to the group callback when all
1003subrequests have finished and set thre groups errno to the current value 1695subrequests have finished and set the groups errno to the current value
1004of errno (just like calling C<errno> without an error number). By default, 1696of errno (just like calling C<errno> without an error number). By default,
1005no argument will be passed and errno is zero. 1697no argument will be passed and errno is zero.
1006 1698
1007=item $grp->errno ([$errno]) 1699=item $grp->errno ([$errno])
1008 1700
1019=item feed $grp $callback->($grp) 1711=item feed $grp $callback->($grp)
1020 1712
1021Sets a feeder/generator on this group: every group can have an attached 1713Sets a feeder/generator on this group: every group can have an attached
1022generator that generates requests if idle. The idea behind this is that, 1714generator that generates requests if idle. The idea behind this is that,
1023although you could just queue as many requests as you want in a group, 1715although you could just queue as many requests as you want in a group,
1024this might starve other requests for a potentially long time. For 1716this might starve other requests for a potentially long time. For example,
1025example, C<aio_scandir> might generate hundreds of thousands C<aio_stat> 1717C<aio_scandir> might generate hundreds of thousands of C<aio_stat>
1026requests, delaying any later requests for a long time. 1718requests, delaying any later requests for a long time.
1027 1719
1028To avoid this, and allow incremental generation of requests, you can 1720To avoid this, and allow incremental generation of requests, you can
1029instead a group and set a feeder on it that generates those requests. The 1721instead a group and set a feeder on it that generates those requests. The
1030feed callback will be called whenever there are few enough (see C<limit>, 1722feed callback will be called whenever there are few enough (see C<limit>,
1035not impose any limits). 1727not impose any limits).
1036 1728
1037If the feed does not queue more requests when called, it will be 1729If the feed does not queue more requests when called, it will be
1038automatically removed from the group. 1730automatically removed from the group.
1039 1731
1040If the feed limit is C<0>, it will be set to C<2> automatically. 1732If the feed limit is C<0> when this method is called, it will be set to
1733C<2> automatically.
1041 1734
1042Example: 1735Example:
1043 1736
1044 # stat all files in @files, but only ever use four aio requests concurrently: 1737 # stat all files in @files, but only ever use four aio requests concurrently:
1045 1738
1057Sets the feeder limit for the group: The feeder will be called whenever 1750Sets the feeder limit for the group: The feeder will be called whenever
1058the group contains less than this many requests. 1751the group contains less than this many requests.
1059 1752
1060Setting the limit to C<0> will pause the feeding process. 1753Setting the limit to C<0> will pause the feeding process.
1061 1754
1755The default value for the limit is C<0>, but note that setting a feeder
1756automatically bumps it up to C<2>.
1757
1062=back 1758=back
1063 1759
1064=head2 SUPPORT FUNCTIONS 1760=head2 SUPPORT FUNCTIONS
1065 1761
1066=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION 1762=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1068=over 4 1764=over 4
1069 1765
1070=item $fileno = IO::AIO::poll_fileno 1766=item $fileno = IO::AIO::poll_fileno
1071 1767
1072Return the I<request result pipe file descriptor>. This filehandle must be 1768Return the I<request result pipe file descriptor>. This filehandle must be
1073polled for reading by some mechanism outside this module (e.g. Event or 1769polled for reading by some mechanism outside this module (e.g. EV, Glib,
1074select, see below or the SYNOPSIS). If the pipe becomes readable you have 1770select and so on, see below or the SYNOPSIS). If the pipe becomes readable
1075to call C<poll_cb> to check the results. 1771you have to call C<poll_cb> to check the results.
1076 1772
1077See C<poll_cb> for an example. 1773See C<poll_cb> for an example.
1078 1774
1079=item IO::AIO::poll_cb 1775=item IO::AIO::poll_cb
1080 1776
1081Process some outstanding events on the result pipe. You have to call this 1777Process some requests that have reached the result phase (i.e. they have
1082regularly. Returns the number of events processed. Returns immediately 1778been executed but the results are not yet reported). You have to call
1083when no events are outstanding. The amount of events processed depends on 1779this "regularly" to finish outstanding requests.
1084the settings of C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
1085 1780
1781Returns C<0> if all events could be processed (or there were no
1782events to process), or C<-1> if it returned earlier for whatever
1783reason. Returns immediately when no events are outstanding. The amount
1784of events processed depends on the settings of C<IO::AIO::max_poll_req>,
1785C<IO::AIO::max_poll_time> and C<IO::AIO::max_outstanding>.
1786
1086If not all requests were processed for whatever reason, the filehandle 1787If not all requests were processed for whatever reason, the poll file
1087will still be ready when C<poll_cb> returns. 1788descriptor will still be ready when C<poll_cb> returns, so normally you
1789don't have to do anything special to have it called later.
1790
1791Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
1792ready, it can be beneficial to call this function from loops which submit
1793a lot of requests, to make sure the results get processed when they become
1794available and not just when the loop is finished and the event loop takes
1795over again. This function returns very fast when there are no outstanding
1796requests.
1088 1797
1089Example: Install an Event watcher that automatically calls 1798Example: Install an Event watcher that automatically calls
1090IO::AIO::poll_cb with high priority: 1799IO::AIO::poll_cb with high priority (more examples can be found in the
1800SYNOPSIS section, at the top of this document):
1091 1801
1092 Event->io (fd => IO::AIO::poll_fileno, 1802 Event->io (fd => IO::AIO::poll_fileno,
1093 poll => 'r', async => 1, 1803 poll => 'r', async => 1,
1094 cb => \&IO::AIO::poll_cb); 1804 cb => \&IO::AIO::poll_cb);
1805
1806=item IO::AIO::poll_wait
1807
1808Wait until either at least one request is in the result phase or no
1809requests are outstanding anymore.
1810
1811This is useful if you want to synchronously wait for some requests to
1812become ready, without actually handling them.
1813
1814See C<nreqs> for an example.
1815
1816=item IO::AIO::poll
1817
1818Waits until some requests have been handled.
1819
1820Returns the number of requests processed, but is otherwise strictly
1821equivalent to:
1822
1823 IO::AIO::poll_wait, IO::AIO::poll_cb
1824
1825=item IO::AIO::flush
1826
1827Wait till all outstanding AIO requests have been handled.
1828
1829Strictly equivalent to:
1830
1831 IO::AIO::poll_wait, IO::AIO::poll_cb
1832 while IO::AIO::nreqs;
1095 1833
1096=item IO::AIO::max_poll_reqs $nreqs 1834=item IO::AIO::max_poll_reqs $nreqs
1097 1835
1098=item IO::AIO::max_poll_time $seconds 1836=item IO::AIO::max_poll_time $seconds
1099 1837
1124 # use a low priority so other tasks have priority 1862 # use a low priority so other tasks have priority
1125 Event->io (fd => IO::AIO::poll_fileno, 1863 Event->io (fd => IO::AIO::poll_fileno,
1126 poll => 'r', nice => 1, 1864 poll => 'r', nice => 1,
1127 cb => &IO::AIO::poll_cb); 1865 cb => &IO::AIO::poll_cb);
1128 1866
1129=item IO::AIO::poll_wait
1130
1131If there are any outstanding requests and none of them in the result
1132phase, wait till the result filehandle becomes ready for reading (simply
1133does a C<select> on the filehandle. This is useful if you want to
1134synchronously wait for some requests to finish).
1135
1136See C<nreqs> for an example.
1137
1138=item IO::AIO::poll
1139
1140Waits until some requests have been handled.
1141
1142Returns the number of requests processed, but is otherwise strictly
1143equivalent to:
1144
1145 IO::AIO::poll_wait, IO::AIO::poll_cb
1146
1147=item IO::AIO::flush
1148
1149Wait till all outstanding AIO requests have been handled.
1150
1151Strictly equivalent to:
1152
1153 IO::AIO::poll_wait, IO::AIO::poll_cb
1154 while IO::AIO::nreqs;
1155
1156=back 1867=back
1157 1868
1158=head3 CONTROLLING THE NUMBER OF THREADS 1869=head3 CONTROLLING THE NUMBER OF THREADS
1159 1870
1160=over 1871=over
1193 1904
1194Under normal circumstances you don't need to call this function. 1905Under normal circumstances you don't need to call this function.
1195 1906
1196=item IO::AIO::max_idle $nthreads 1907=item IO::AIO::max_idle $nthreads
1197 1908
1198Limit the number of threads (default: 4) that are allowed to idle (i.e., 1909Limit the number of threads (default: 4) that are allowed to idle
1199threads that did not get a request to process within 10 seconds). That 1910(i.e., threads that did not get a request to process within the idle
1200means if a thread becomes idle while C<$nthreads> other threads are also 1911timeout (default: 10 seconds). That means if a thread becomes idle while
1201idle, it will free its resources and exit. 1912C<$nthreads> other threads are also idle, it will free its resources and
1913exit.
1202 1914
1203This is useful when you allow a large number of threads (e.g. 100 or 1000) 1915This is useful when you allow a large number of threads (e.g. 100 or 1000)
1204to allow for extremely high load situations, but want to free resources 1916to allow for extremely high load situations, but want to free resources
1205under normal circumstances (1000 threads can easily consume 30MB of RAM). 1917under normal circumstances (1000 threads can easily consume 30MB of RAM).
1206 1918
1207The default is probably ok in most situations, especially if thread 1919The default is probably ok in most situations, especially if thread
1208creation is fast. If thread creation is very slow on your system you might 1920creation is fast. If thread creation is very slow on your system you might
1209want to use larger values. 1921want to use larger values.
1210 1922
1923=item IO::AIO::idle_timeout $seconds
1924
1925Sets the minimum idle timeout (default 10) after which worker threads are
1926allowed to exit. SEe C<IO::AIO::max_idle>.
1927
1211=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs 1928=item IO::AIO::max_outstanding $maxreqs
1929
1930Sets the maximum number of outstanding requests to C<$nreqs>. If
1931you do queue up more than this number of requests, the next call to
1932C<IO::AIO::poll_cb> (and other functions calling C<poll_cb>, such as
1933C<IO::AIO::flush> or C<IO::AIO::poll>) will block until the limit is no
1934longer exceeded.
1935
1936In other words, this setting does not enforce a queue limit, but can be
1937used to make poll functions block if the limit is exceeded.
1212 1938
1213This is a very bad function to use in interactive programs because it 1939This is a very bad function to use in interactive programs because it
1214blocks, and a bad way to reduce concurrency because it is inexact: Better 1940blocks, and a bad way to reduce concurrency because it is inexact: Better
1215use an C<aio_group> together with a feed callback. 1941use an C<aio_group> together with a feed callback.
1216 1942
1217Sets the maximum number of outstanding requests to C<$nreqs>. If you 1943Its main use is in scripts without an event loop - when you want to stat
1218do queue up more than this number of requests, the next call to the 1944a lot of files, you can write somehting like this:
1219C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
1220function will block until the limit is no longer exceeded.
1221 1945
1222The default value is very large, so there is no practical limit on the 1946 IO::AIO::max_outstanding 32;
1223number of outstanding requests.
1224 1947
1225You can still queue as many requests as you want. Therefore, 1948 for my $path (...) {
1226C<max_oustsanding> is mainly useful in simple scripts (with low values) or 1949 aio_stat $path , ...;
1227as a stop gap to shield against fatal memory overflow (with large values). 1950 IO::AIO::poll_cb;
1951 }
1952
1953 IO::AIO::flush;
1954
1955The call to C<poll_cb> inside the loop will normally return instantly, but
1956as soon as more thna C<32> reqeusts are in-flight, it will block until
1957some requests have been handled. This keeps the loop from pushing a large
1958number of C<aio_stat> requests onto the queue.
1959
1960The default value for C<max_outstanding> is very large, so there is no
1961practical limit on the number of outstanding requests.
1228 1962
1229=back 1963=back
1230 1964
1231=head3 STATISTICAL INFORMATION 1965=head3 STATISTICAL INFORMATION
1232 1966
1252Returns the number of requests currently in the pending state (executed, 1986Returns the number of requests currently in the pending state (executed,
1253but not yet processed by poll_cb). 1987but not yet processed by poll_cb).
1254 1988
1255=back 1989=back
1256 1990
1991=head3 MISCELLANEOUS FUNCTIONS
1992
1993IO::AIO implements some functions that are useful when you want to use
1994some "Advanced I/O" function not available to in Perl, without going the
1995"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
1996counterpart.
1997
1998=over 4
1999
2000=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
2001
2002Calls the C<eio_sendfile_sync> function, which is like C<aio_sendfile>,
2003but is blocking (this makes most sense if you know the input data is
2004likely cached already and the output filehandle is set to non-blocking
2005operations).
2006
2007Returns the number of bytes copied, or C<-1> on error.
2008
2009=item IO::AIO::fadvise $fh, $offset, $len, $advice
2010
2011Simply calls the C<posix_fadvise> function (see its
2012manpage for details). The following advice constants are
2013available: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
2014C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
2015C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
2016
2017On systems that do not implement C<posix_fadvise>, this function returns
2018ENOSYS, otherwise the return value of C<posix_fadvise>.
2019
2020=item IO::AIO::madvise $scalar, $offset, $len, $advice
2021
2022Simply calls the C<posix_madvise> function (see its
2023manpage for details). The following advice constants are
2024available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
2025C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>.
2026
2027On systems that do not implement C<posix_madvise>, this function returns
2028ENOSYS, otherwise the return value of C<posix_madvise>.
2029
2030=item IO::AIO::mprotect $scalar, $offset, $len, $protect
2031
2032Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
2033$scalar (see its manpage for details). The following protect
2034constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
2035C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
2036
2037On systems that do not implement C<mprotect>, this function returns
2038ENOSYS, otherwise the return value of C<mprotect>.
2039
2040=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
2041
2042Memory-maps a file (or anonymous memory range) and attaches it to the
2043given C<$scalar>, which will act like a string scalar. Returns true on
2044success, and false otherwise.
2045
2046The only operations allowed on the scalar are C<substr>/C<vec> that don't
2047change the string length, and most read-only operations such as copying it
2048or searching it with regexes and so on.
2049
2050Anything else is unsafe and will, at best, result in memory leaks.
2051
2052The memory map associated with the C<$scalar> is automatically removed
2053when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or
2054C<IO::AIO::munmap> functions are called.
2055
2056This calls the C<mmap>(2) function internally. See your system's manual
2057page for details on the C<$length>, C<$prot> and C<$flags> parameters.
2058
2059The C<$length> must be larger than zero and smaller than the actual
2060filesize.
2061
2062C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>,
2063C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
2064
2065C<$flags> can be a combination of
2066C<IO::AIO::MAP_SHARED> or
2067C<IO::AIO::MAP_PRIVATE>,
2068or a number of system-specific flags (when not available, the are C<0>):
2069C<IO::AIO::MAP_ANONYMOUS> (which is set to C<MAP_ANON> if your system only provides this constant),
2070C<IO::AIO::MAP_LOCKED>,
2071C<IO::AIO::MAP_NORESERVE>,
2072C<IO::AIO::MAP_POPULATE>,
2073C<IO::AIO::MAP_NONBLOCK>,
2074C<IO::AIO::MAP_FIXED>,
2075C<IO::AIO::MAP_GROWSDOWN>,
2076C<IO::AIO::MAP_32BIT>,
2077C<IO::AIO::MAP_HUGETLB> or
2078C<IO::AIO::MAP_STACK>.
2079
2080If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2081
2082C<$offset> is the offset from the start of the file - it generally must be
2083a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
2084
2085Example:
2086
2087 use Digest::MD5;
2088 use IO::AIO;
2089
2090 open my $fh, "<verybigfile"
2091 or die "$!";
2092
2093 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
2094 or die "verybigfile: $!";
2095
2096 my $fast_md5 = md5 $data;
2097
2098=item IO::AIO::munmap $scalar
2099
2100Removes a previous mmap and undefines the C<$scalar>.
2101
2102=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
2103
2104Calls the C<munlock> function, undoing the effects of a previous
2105C<aio_mlock> call (see its description for details).
2106
2107=item IO::AIO::munlockall
2108
2109Calls the C<munlockall> function.
2110
2111On systems that do not implement C<munlockall>, this function returns
2112ENOSYS, otherwise the return value of C<munlockall>.
2113
2114=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
2115
2116Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
2117C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
2118should be the file offset.
2119
2120C<$r_fh> and C<$w_fh> should not refer to the same file, as splice might
2121silently corrupt the data in this case.
2122
2123The following symbol flag values are available: C<IO::AIO::SPLICE_F_MOVE>,
2124C<IO::AIO::SPLICE_F_NONBLOCK>, C<IO::AIO::SPLICE_F_MORE> and
2125C<IO::AIO::SPLICE_F_GIFT>.
2126
2127See the C<splice(2)> manpage for details.
2128
2129=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2130
2131Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
2132description for C<IO::AIO::splice> above for details.
2133
2134=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2135
2136Attempts to query or change the pipe buffer size. Obviously works only
2137on pipes, and currently works only on GNU/Linux systems, and fails with
2138C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2139size on other systems, drop me a note.
2140
2141=item ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
2142
2143This is a direct interface to the Linux L<pipe2(2)> system call. If
2144C<$flags> is missing or C<0>, then this should be the same as a call to
2145perl's built-in C<pipe> function and create a new pipe, and works on
2146systems that lack the pipe2 syscall. On win32, this case invokes C<_pipe
2147(..., 4096, O_BINARY)>.
2148
2149If C<$flags> is non-zero, it tries to invoke the pipe2 system call with
2150the given flags (Linux 2.6.27, glibc 2.9).
2151
2152On success, the read and write file handles are returned.
2153
2154On error, nothing will be returned. If the pipe2 syscall is missing and
2155C<$flags> is non-zero, fails with C<ENOSYS>.
2156
2157Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
2158time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
2159C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported.
2160
2161=back
2162
1257=cut 2163=cut
1258 2164
1259min_parallel 8; 2165min_parallel 8;
1260 2166
1261END { flush } 2167END { flush }
1262 2168
12631; 21691;
1264 2170
2171=head1 EVENT LOOP INTEGRATION
2172
2173It is recommended to use L<AnyEvent::AIO> to integrate IO::AIO
2174automatically into many event loops:
2175
2176 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
2177 use AnyEvent::AIO;
2178
2179You can also integrate IO::AIO manually into many event loops, here are
2180some examples of how to do this:
2181
2182 # EV integration
2183 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
2184
2185 # Event integration
2186 Event->io (fd => IO::AIO::poll_fileno,
2187 poll => 'r',
2188 cb => \&IO::AIO::poll_cb);
2189
2190 # Glib/Gtk2 integration
2191 add_watch Glib::IO IO::AIO::poll_fileno,
2192 in => sub { IO::AIO::poll_cb; 1 };
2193
2194 # Tk integration
2195 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
2196 readable => \&IO::AIO::poll_cb);
2197
2198 # Danga::Socket integration
2199 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
2200 \&IO::AIO::poll_cb);
2201
1265=head2 FORK BEHAVIOUR 2202=head2 FORK BEHAVIOUR
1266 2203
1267This module should do "the right thing" when the process using it forks: 2204Usage of pthreads in a program changes the semantics of fork
2205considerably. Specifically, only async-safe functions can be called after
2206fork. Perl doesn't know about this, so in general, you cannot call fork
2207with defined behaviour in perl if pthreads are involved. IO::AIO uses
2208pthreads, so this applies, but many other extensions and (for inexplicable
2209reasons) perl itself often is linked against pthreads, so this limitation
2210applies to quite a lot of perls.
1268 2211
1269Before the fork, IO::AIO enters a quiescent state where no requests 2212This module no longer tries to fight your OS, or POSIX. That means IO::AIO
1270can be added in other threads and no results will be processed. After 2213only works in the process that loaded it. Forking is fully supported, but
1271the fork the parent simply leaves the quiescent state and continues 2214using IO::AIO in the child is not.
1272request/result processing, while the child frees the request/result queue
1273(so that the requests started before the fork will only be handled in the
1274parent). Threads will be started on demand until the limit set in the
1275parent process has been reached again.
1276 2215
1277In short: the parent will, after a short pause, continue as if fork had 2216You might get around by not I<using> IO::AIO before (or after)
1278not been called, while the child will act as if IO::AIO has not been used 2217forking. You could also try to call the L<IO::AIO::reinit> function in the
1279yet. 2218child:
2219
2220=over 4
2221
2222=item IO::AIO::reinit
2223
2224Abandons all current requests and I/O threads and simply reinitialises all
2225data structures. This is not an operation supported by any standards, but
2226happens to work on GNU/Linux and some newer BSD systems.
2227
2228The only reasonable use for this function is to call it after forking, if
2229C<IO::AIO> was used in the parent. Calling it while IO::AIO is active in
2230the process will result in undefined behaviour. Calling it at any time
2231will also result in any undefined (by POSIX) behaviour.
2232
2233=back
1280 2234
1281=head2 MEMORY USAGE 2235=head2 MEMORY USAGE
1282 2236
1283Per-request usage: 2237Per-request usage:
1284 2238
1301 2255
1302Known bugs will be fixed in the next release. 2256Known bugs will be fixed in the next release.
1303 2257
1304=head1 SEE ALSO 2258=head1 SEE ALSO
1305 2259
1306L<Coro::AIO>. 2260L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
2261more natural syntax.
1307 2262
1308=head1 AUTHOR 2263=head1 AUTHOR
1309 2264
1310 Marc Lehmann <schmorp@schmorp.de> 2265 Marc Lehmann <schmorp@schmorp.de>
1311 http://home.schmorp.de/ 2266 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines