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.176 by root, Sun Jan 10 23:05:11 2010 UTC vs.
Revision 1.275 by root, Fri Sep 22 05:20:39 2017 UTC

1=head1 NAME 1=head1 NAME
2 2
3IO::AIO - Asynchronous Input/Output 3IO::AIO - Asynchronous/Advanced Input/Output
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
58not well-supported or restricted (GNU/Linux doesn't allow them on normal 58not well-supported or restricted (GNU/Linux doesn't allow them on normal
59files currently, for example), and they would only support aio_read and 59files currently, for example), and they would only support aio_read and
60aio_write, so the remaining functionality would have to be implemented 60aio_write, so the remaining functionality would have to be implemented
61using threads anyway. 61using threads anyway.
62 62
63In addition to asynchronous I/O, this module also exports some rather
64arcane interfaces, such as C<madvise> or linux's C<splice> system call,
65which is why the C<A> in C<AIO> can also mean I<advanced>.
66
63Although the module will work in the presence of other (Perl-) threads, 67Although the module will work in the presence of other (Perl-) threads,
64it is currently not reentrant in any way, so use appropriate locking 68it is currently not reentrant in any way, so use appropriate locking
65yourself, always call C<poll_cb> from within the same thread, or never 69yourself, always call C<poll_cb> from within the same thread, or never
66call C<poll_cb> (or other C<aio_> functions) recursively. 70call C<poll_cb> (or other C<aio_> functions) recursively.
67 71
68=head2 EXAMPLE 72=head2 EXAMPLE
69 73
70This is a simple example that uses the EV module and loads 74This is a simple example that uses the EV module and loads
71F</etc/passwd> asynchronously: 75F</etc/passwd> asynchronously:
72 76
73 use Fcntl;
74 use EV; 77 use EV;
75 use IO::AIO; 78 use IO::AIO;
76 79
77 # register the IO::AIO callback with EV 80 # register the IO::AIO callback with EV
78 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 81 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
79 82
80 # queue the request to open /etc/passwd 83 # queue the request to open /etc/passwd
81 aio_open "/etc/passwd", O_RDONLY, 0, sub { 84 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
82 my $fh = shift 85 my $fh = shift
83 or die "error while opening: $!"; 86 or die "error while opening: $!";
84 87
85 # stat'ing filehandles is generally non-blocking 88 # stat'ing filehandles is generally non-blocking
86 my $size = -s $fh; 89 my $size = -s $fh;
95 98
96 # file contents now in $contents 99 # file contents now in $contents
97 print $contents; 100 print $contents;
98 101
99 # exit event loop and program 102 # exit event loop and program
100 EV::unloop; 103 EV::break;
101 }; 104 };
102 }; 105 };
103 106
104 # possibly queue up other requests, or open GUI windows, 107 # possibly queue up other requests, or open GUI windows,
105 # check for sockets etc. etc. 108 # check for sockets etc. etc.
106 109
107 # process events as long as there are some: 110 # process events as long as there are some:
108 EV::loop; 111 EV::run;
109 112
110=head1 REQUEST ANATOMY AND LIFETIME 113=head1 REQUEST ANATOMY AND LIFETIME
111 114
112Every C<aio_*> function creates a request. which is a C data structure not 115Every C<aio_*> function creates a request. which is a C data structure not
113directly visible to Perl. 116directly visible to Perl.
168use common::sense; 171use common::sense;
169 172
170use base 'Exporter'; 173use base 'Exporter';
171 174
172BEGIN { 175BEGIN {
173 our $VERSION = '3.5'; 176 our $VERSION = 4.35;
174 177
175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close 178 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 179 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync 180 aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl
178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead 181 aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
182 aio_pathsync aio_readahead aio_fiemap aio_allocate
179 aio_rename aio_link aio_move aio_copy aio_group 183 aio_rename aio_rename2 aio_link aio_move aio_copy aio_group
180 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown 184 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
181 aio_chmod aio_utime aio_truncate 185 aio_chmod aio_utime aio_truncate
182 aio_msync aio_mtouch aio_statvfs); 186 aio_msync aio_mtouch aio_mlock aio_mlockall
187 aio_statvfs
188 aio_wd);
183 189
184 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 190 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
185 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 191 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
186 min_parallel max_parallel max_idle 192 min_parallel max_parallel max_idle idle_timeout
187 nreqs nready npending nthreads 193 nreqs nready npending nthreads
188 max_poll_time max_poll_reqs 194 max_poll_time max_poll_reqs
189 sendfile fadvise); 195 sendfile fadvise madvise
196 mmap munmap munlock munlockall);
190 197
191 push @AIO_REQ, qw(aio_busy); # not exported 198 push @AIO_REQ, qw(aio_busy); # not exported
192 199
193 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 200 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
194 201
198 205
199=head1 FUNCTIONS 206=head1 FUNCTIONS
200 207
201=head2 QUICK OVERVIEW 208=head2 QUICK OVERVIEW
202 209
203This section simply lists the prototypes of the most important functions 210This section simply lists the prototypes most of the functions for
204for quick reference. See the following sections for function-by-function 211quick reference. See the following sections for function-by-function
205documentation. 212documentation.
206 213
214 aio_wd $pathname, $callback->($wd)
207 aio_open $pathname, $flags, $mode, $callback->($fh) 215 aio_open $pathname, $flags, $mode, $callback->($fh)
208 aio_close $fh, $callback->($status) 216 aio_close $fh, $callback->($status)
217 aio_seek $fh,$offset,$whence, $callback->($offs)
209 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 218 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
210 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 219 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
211 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 220 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
212 aio_readahead $fh,$offset,$length, $callback->($retval) 221 aio_readahead $fh,$offset,$length, $callback->($retval)
213 aio_stat $fh_or_path, $callback->($status) 222 aio_stat $fh_or_path, $callback->($status)
214 aio_lstat $fh, $callback->($status) 223 aio_lstat $fh, $callback->($status)
215 aio_statvfs $fh_or_path, $callback->($statvfs) 224 aio_statvfs $fh_or_path, $callback->($statvfs)
216 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 225 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
217 aio_chown $fh_or_path, $uid, $gid, $callback->($status) 226 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
227 aio_chmod $fh_or_path, $mode, $callback->($status)
218 aio_truncate $fh_or_path, $offset, $callback->($status) 228 aio_truncate $fh_or_path, $offset, $callback->($status)
219 aio_chmod $fh_or_path, $mode, $callback->($status) 229 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
230 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
220 aio_unlink $pathname, $callback->($status) 231 aio_unlink $pathname, $callback->($status)
221 aio_mknod $path, $mode, $dev, $callback->($status) 232 aio_mknod $pathname, $mode, $dev, $callback->($status)
222 aio_link $srcpath, $dstpath, $callback->($status) 233 aio_link $srcpath, $dstpath, $callback->($status)
223 aio_symlink $srcpath, $dstpath, $callback->($status) 234 aio_symlink $srcpath, $dstpath, $callback->($status)
224 aio_readlink $path, $callback->($link) 235 aio_readlink $pathname, $callback->($link)
236 aio_realpath $pathname, $callback->($path)
225 aio_rename $srcpath, $dstpath, $callback->($status) 237 aio_rename $srcpath, $dstpath, $callback->($status)
238 aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
226 aio_mkdir $pathname, $mode, $callback->($status) 239 aio_mkdir $pathname, $mode, $callback->($status)
227 aio_rmdir $pathname, $callback->($status) 240 aio_rmdir $pathname, $callback->($status)
228 aio_readdir $pathname, $callback->($entries) 241 aio_readdir $pathname, $callback->($entries)
229 aio_readdirx $pathname, $flags, $callback->($entries, $flags) 242 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
230 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST 243 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
231 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN 244 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
245 aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
232 aio_load $path, $data, $callback->($status) 246 aio_load $pathname, $data, $callback->($status)
233 aio_copy $srcpath, $dstpath, $callback->($status) 247 aio_copy $srcpath, $dstpath, $callback->($status)
234 aio_move $srcpath, $dstpath, $callback->($status) 248 aio_move $srcpath, $dstpath, $callback->($status)
235 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
236 aio_rmtree $path, $callback->($status) 249 aio_rmtree $pathname, $callback->($status)
250 aio_fcntl $fh, $cmd, $arg, $callback->($status)
251 aio_ioctl $fh, $request, $buf, $callback->($status)
237 aio_sync $callback->($status) 252 aio_sync $callback->($status)
253 aio_syncfs $fh, $callback->($status)
238 aio_fsync $fh, $callback->($status) 254 aio_fsync $fh, $callback->($status)
239 aio_fdatasync $fh, $callback->($status) 255 aio_fdatasync $fh, $callback->($status)
240 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 256 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
241 aio_pathsync $path, $callback->($status) 257 aio_pathsync $pathname, $callback->($status)
242 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 258 aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
243 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 259 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
260 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
261 aio_mlockall $flags, $callback->($status)
244 aio_group $callback->(...) 262 aio_group $callback->(...)
245 aio_nop $callback->() 263 aio_nop $callback->()
246 264
247 $prev_pri = aioreq_pri [$pri] 265 $prev_pri = aioreq_pri [$pri]
248 aioreq_nice $pri_adjust 266 aioreq_nice $pri_adjust
254 IO::AIO::max_poll_reqs $nreqs 272 IO::AIO::max_poll_reqs $nreqs
255 IO::AIO::max_poll_time $seconds 273 IO::AIO::max_poll_time $seconds
256 IO::AIO::min_parallel $nthreads 274 IO::AIO::min_parallel $nthreads
257 IO::AIO::max_parallel $nthreads 275 IO::AIO::max_parallel $nthreads
258 IO::AIO::max_idle $nthreads 276 IO::AIO::max_idle $nthreads
277 IO::AIO::idle_timeout $seconds
259 IO::AIO::max_outstanding $maxreqs 278 IO::AIO::max_outstanding $maxreqs
260 IO::AIO::nreqs 279 IO::AIO::nreqs
261 IO::AIO::nready 280 IO::AIO::nready
262 IO::AIO::npending 281 IO::AIO::npending
282 IO::AIO::min_fdlimit $nfd;
263 283
264 IO::AIO::sendfile $ofh, $ifh, $offset, $count 284 IO::AIO::sendfile $ofh, $ifh, $offset, $count
265 IO::AIO::fadvise $fh, $offset, $len, $advice 285 IO::AIO::fadvise $fh, $offset, $len, $advice
266 IO::AIO::mlockall $flags 286 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
287 IO::AIO::munmap $scalar
288 IO::AIO::madvise $scalar, $offset, $length, $advice
289 IO::AIO::mprotect $scalar, $offset, $length, $protect
290 IO::AIO::munlock $scalar, $offset = 0, $length = undef
267 IO::AIO::munlockall 291 IO::AIO::munlockall
268 292
269=head2 AIO REQUEST FUNCTIONS 293=head2 API NOTES
270 294
271All the C<aio_*> calls are more or less thin wrappers around the syscall 295All the C<aio_*> calls are more or less thin wrappers around the syscall
272with the same name (sans C<aio_>). The arguments are similar or identical, 296with the same name (sans C<aio_>). The arguments are similar or identical,
273and they all accept an additional (and optional) C<$callback> argument 297and they all accept an additional (and optional) C<$callback> argument
274which must be a code reference. This code reference will get called with 298which must be a code reference. This code reference will be called after
275the syscall return code (e.g. most syscalls return C<-1> on error, unlike 299the syscall has been executed in an asynchronous fashion. The results
276perl, which usually delivers "false") as its sole argument after the given 300of the request will be passed as arguments to the callback (and, if an
277syscall has been executed asynchronously. 301error occured, in C<$!>) - for most requests the syscall return code (e.g.
302most syscalls return C<-1> on error, unlike perl, which usually delivers
303"false").
304
305Some requests (such as C<aio_readdir>) pass the actual results and
306communicate failures by passing C<undef>.
278 307
279All functions expecting a filehandle keep a copy of the filehandle 308All functions expecting a filehandle keep a copy of the filehandle
280internally until the request has finished. 309internally until the request has finished.
281 310
282All functions return request objects of type L<IO::AIO::REQ> that allow 311All functions return request objects of type L<IO::AIO::REQ> that allow
283further manipulation of those requests while they are in-flight. 312further manipulation of those requests while they are in-flight.
284 313
285The pathnames you pass to these routines I<must> be absolute and 314The pathnames you pass to these routines I<should> be absolute. The
286encoded as octets. The reason for the former is that at the time the 315reason for this is that at the time the request is being executed, the
287request is being executed, the current working directory could have 316current working directory could have changed. Alternatively, you can
288changed. Alternatively, you can make sure that you never change the 317make sure that you never change the current working directory anywhere
289current working directory anywhere in the program and then use relative 318in the program and then use relative paths. You can also take advantage
290paths. 319of IO::AIOs working directory abstraction, that lets you specify paths
320relative to some previously-opened "working directory object" - see the
321description of the C<IO::AIO::WD> class later in this document.
291 322
292To encode pathnames as octets, either make sure you either: a) always pass 323To encode pathnames as octets, either make sure you either: a) always pass
293in filenames you got from outside (command line, readdir etc.) without 324in filenames you got from outside (command line, readdir etc.) without
294tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode 325tinkering, b) are in your native filesystem encoding, c) use the Encode
295your pathnames to the locale (or other) encoding in effect in the user 326module and encode your pathnames to the locale (or other) encoding in
296environment, d) use Glib::filename_from_unicode on unicode filenames or e) 327effect in the user environment, d) use Glib::filename_from_unicode on
297use something else to ensure your scalar has the correct contents. 328unicode filenames or e) use something else to ensure your scalar has the
329correct contents.
298 330
299This works, btw. independent of the internal UTF-8 bit, which IO::AIO 331This works, btw. independent of the internal UTF-8 bit, which IO::AIO
300handles correctly whether it is set or not. 332handles correctly whether it is set or not.
333
334=head2 AIO REQUEST FUNCTIONS
301 335
302=over 4 336=over 4
303 337
304=item $prev_pri = aioreq_pri [$pri] 338=item $prev_pri = aioreq_pri [$pri]
305 339
335 369
336 370
337=item aio_open $pathname, $flags, $mode, $callback->($fh) 371=item aio_open $pathname, $flags, $mode, $callback->($fh)
338 372
339Asynchronously open or create a file and call the callback with a newly 373Asynchronously open or create a file and call the callback with a newly
340created filehandle for the file. 374created filehandle for the file (or C<undef> in case of an error).
341 375
342The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 376The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
343for an explanation. 377for an explanation.
344 378
345The C<$flags> argument is a bitmask. See the C<Fcntl> module for a 379The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
352by the umask in effect then the request is being executed, so better never 386by the umask in effect then the request is being executed, so better never
353change the umask. 387change the umask.
354 388
355Example: 389Example:
356 390
357 aio_open "/etc/passwd", O_RDONLY, 0, sub { 391 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
358 if ($_[0]) { 392 if ($_[0]) {
359 print "open successful, fh is $_[0]\n"; 393 print "open successful, fh is $_[0]\n";
360 ... 394 ...
361 } else { 395 } else {
362 die "open failed: $!\n"; 396 die "open failed: $!\n";
363 } 397 }
364 }; 398 };
365 399
400In addition to all the common open modes/flags (C<O_RDONLY>, C<O_WRONLY>,
401C<O_RDWR>, C<O_CREAT>, C<O_TRUNC>, C<O_EXCL> and C<O_APPEND>), the
402following POSIX and non-POSIX constants are available (missing ones on
403your system are, as usual, C<0>):
404
405C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
406C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
407C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, and C<O_TTY_INIT>.
408
366 409
367=item aio_close $fh, $callback->($status) 410=item aio_close $fh, $callback->($status)
368 411
369Asynchronously close a file and call the callback with the result 412Asynchronously close a file and call the callback with the result
370code. 413code.
379Or in other words: the file descriptor will be closed, but it will not be 422Or in other words: the file descriptor will be closed, but it will not be
380free for reuse until the perl filehandle is closed. 423free for reuse until the perl filehandle is closed.
381 424
382=cut 425=cut
383 426
427=item aio_seek $fh, $offset, $whence, $callback->($offs)
428
429Seeks the filehandle to the new C<$offset>, similarly to perl's
430C<sysseek>. The C<$whence> can use the traditional values (C<0> for
431C<IO::AIO::SEEK_SET>, C<1> for C<IO::AIO::SEEK_CUR> or C<2> for
432C<IO::AIO::SEEK_END>).
433
434The resulting absolute offset will be passed to the callback, or C<-1> in
435case of an error.
436
437In theory, the C<$whence> constants could be different than the
438corresponding values from L<Fcntl>, but perl guarantees they are the same,
439so don't panic.
440
441As a GNU/Linux (and maybe Solaris) extension, also the constants
442C<IO::AIO::SEEK_DATA> and C<IO::AIO::SEEK_HOLE> are available, if they
443could be found. No guarantees about suitability for use in C<aio_seek> or
444Perl's C<sysseek> can be made though, although I would naively assume they
445"just work".
446
384=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 447=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
385 448
386=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 449=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
387 450
388Reads or writes C<$length> bytes from or to the specified C<$fh> and 451Reads or writes C<$length> bytes from or to the specified C<$fh> and
389C<$offset> into the scalar given by C<$data> and offset C<$dataoffset> 452C<$offset> into the scalar given by C<$data> and offset C<$dataoffset> and
390and calls the callback without the actual number of bytes read (or -1 on 453calls the callback with the actual number of bytes transferred (or -1 on
391error, just like the syscall). 454error, just like the syscall).
392 455
393C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to 456C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to
394offset plus the actual number of bytes read. 457offset plus the actual number of bytes read.
395 458
420 483
421Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts 484Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
422reading at byte offset C<$in_offset>, and starts writing at the current 485reading at byte offset C<$in_offset>, and starts writing at the current
423file offset of C<$out_fh>. Because of that, it is not safe to issue more 486file offset of C<$out_fh>. Because of that, it is not safe to issue more
424than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each 487than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
425other. 488other. The same C<$in_fh> works fine though, as this function does not
489move or use the file offset of C<$in_fh>.
426 490
491Please note that C<aio_sendfile> can read more bytes from C<$in_fh> than
492are written, and there is no way to find out how many more bytes have been
493read from C<aio_sendfile> alone, as C<aio_sendfile> only provides the
494number of bytes written to C<$out_fh>. Only if the result value equals
495C<$length> one can assume that C<$length> bytes have been read.
496
497Unlike with other C<aio_> functions, it makes a lot of sense to use
498C<aio_sendfile> on non-blocking sockets, as long as one end (typically
499the C<$in_fh>) is a file - the file I/O will then be asynchronous, while
500the socket I/O will be non-blocking. Note, however, that you can run
501into a trap where C<aio_sendfile> reads some data with readahead, then
502fails to write all data, and when the socket is ready the next time, the
503data in the cache is already lost, forcing C<aio_sendfile> to again hit
504the disk. Explicit C<aio_read> + C<aio_write> let's you better control
505resource usage.
506
427This call tries to make use of a native C<sendfile> syscall to provide 507This call tries to make use of a native C<sendfile>-like syscall to
428zero-copy operation. For this to work, C<$out_fh> should refer to a 508provide zero-copy operation. For this to work, C<$out_fh> should refer to
429socket, and C<$in_fh> should refer to an mmap'able file. 509a socket, and C<$in_fh> should refer to an mmap'able file.
430 510
431If a native sendfile cannot be found or it fails with C<ENOSYS>, 511If a native sendfile cannot be found or it fails with C<ENOSYS>,
432C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>, 512C<EINVAL>, C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or
433it will be emulated, so you can call C<aio_sendfile> on any type of 513C<ENOTSOCK>, it will be emulated, so you can call C<aio_sendfile> on any
434filehandle regardless of the limitations of the operating system. 514type of filehandle regardless of the limitations of the operating system.
435 515
436Please note, however, that C<aio_sendfile> can read more bytes from 516As native sendfile syscalls (as practically any non-POSIX interface hacked
437C<$in_fh> than are written, and there is no way to find out how many 517together in a hurry to improve benchmark numbers) tend to be rather buggy
438bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only 518on many systems, this implementation tries to work around some known bugs
439provides the number of bytes written to C<$out_fh>. Only if the result 519in Linux and FreeBSD kernels (probably others, too), but that might fail,
440value equals C<$length> one can assume that C<$length> bytes have been 520so you really really should check the return value of C<aio_sendfile> -
441read. 521fewer bytes than expected might have been transferred.
442 522
443 523
444=item aio_readahead $fh,$offset,$length, $callback->($retval) 524=item aio_readahead $fh,$offset,$length, $callback->($retval)
445 525
446C<aio_readahead> populates the page cache with data from a file so that 526C<aio_readahead> populates the page cache with data from a file so that
450whole pages, so that offset is effectively rounded down to a page boundary 530whole pages, so that offset is effectively rounded down to a page boundary
451and bytes are read up to the next page boundary greater than or equal to 531and bytes are read up to the next page boundary greater than or equal to
452(off-set+length). C<aio_readahead> does not read beyond the end of the 532(off-set+length). C<aio_readahead> does not read beyond the end of the
453file. The current file offset of the file is left unchanged. 533file. The current file offset of the file is left unchanged.
454 534
455If that syscall doesn't exist (likely if your OS isn't Linux) it will be 535If that syscall doesn't exist (likely if your kernel isn't Linux) it will
456emulated by simply reading the data, which would have a similar effect. 536be emulated by simply reading the data, which would have a similar effect.
457 537
458 538
459=item aio_stat $fh_or_path, $callback->($status) 539=item aio_stat $fh_or_path, $callback->($status)
460 540
461=item aio_lstat $fh, $callback->($status) 541=item aio_lstat $fh, $callback->($status)
468for an explanation. 548for an explanation.
469 549
470Currently, the stats are always 64-bit-stats, i.e. instead of returning an 550Currently, the stats are always 64-bit-stats, i.e. instead of returning an
471error when stat'ing a large file, the results will be silently truncated 551error when stat'ing a large file, the results will be silently truncated
472unless perl itself is compiled with large file support. 552unless perl itself is compiled with large file support.
553
554To help interpret the mode and dev/rdev stat values, IO::AIO offers the
555following constants and functions (if not implemented, the constants will
556be C<0> and the functions will either C<croak> or fall back on traditional
557behaviour).
558
559C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
560C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
561C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
473 562
474Example: Print the length of F</etc/passwd>: 563Example: Print the length of F</etc/passwd>:
475 564
476 aio_stat "/etc/passwd", sub { 565 aio_stat "/etc/passwd", sub {
477 $_[0] and die "stat failed: $!"; 566 $_[0] and die "stat failed: $!";
521 namemax => 255, 610 namemax => 255,
522 frsize => 1024, 611 frsize => 1024,
523 fsid => 1810 612 fsid => 1810
524 } 613 }
525 614
615Here is a (likely partial - send me updates!) list of fsid values used by
616Linux - it is safe to hardcode these when C<$^O> is C<linux>:
617
618 0x0000adf5 adfs
619 0x0000adff affs
620 0x5346414f afs
621 0x09041934 anon-inode filesystem
622 0x00000187 autofs
623 0x42465331 befs
624 0x1badface bfs
625 0x42494e4d binfmt_misc
626 0x9123683e btrfs
627 0x0027e0eb cgroupfs
628 0xff534d42 cifs
629 0x73757245 coda
630 0x012ff7b7 coh
631 0x28cd3d45 cramfs
632 0x453dcd28 cramfs-wend (wrong endianness)
633 0x64626720 debugfs
634 0x00001373 devfs
635 0x00001cd1 devpts
636 0x0000f15f ecryptfs
637 0x00414a53 efs
638 0x0000137d ext
639 0x0000ef53 ext2/ext3/ext4
640 0x0000ef51 ext2
641 0xf2f52010 f2fs
642 0x00004006 fat
643 0x65735546 fuseblk
644 0x65735543 fusectl
645 0x0bad1dea futexfs
646 0x01161970 gfs2
647 0x47504653 gpfs
648 0x00004244 hfs
649 0xf995e849 hpfs
650 0x00c0ffee hostfs
651 0x958458f6 hugetlbfs
652 0x2bad1dea inotifyfs
653 0x00009660 isofs
654 0x000072b6 jffs2
655 0x3153464a jfs
656 0x6b414653 k-afs
657 0x0bd00bd0 lustre
658 0x0000137f minix
659 0x0000138f minix 30 char names
660 0x00002468 minix v2
661 0x00002478 minix v2 30 char names
662 0x00004d5a minix v3
663 0x19800202 mqueue
664 0x00004d44 msdos
665 0x0000564c novell
666 0x00006969 nfs
667 0x6e667364 nfsd
668 0x00003434 nilfs
669 0x5346544e ntfs
670 0x00009fa1 openprom
671 0x7461636F ocfs2
672 0x00009fa0 proc
673 0x6165676c pstorefs
674 0x0000002f qnx4
675 0x68191122 qnx6
676 0x858458f6 ramfs
677 0x52654973 reiserfs
678 0x00007275 romfs
679 0x67596969 rpc_pipefs
680 0x73636673 securityfs
681 0xf97cff8c selinux
682 0x0000517b smb
683 0x534f434b sockfs
684 0x73717368 squashfs
685 0x62656572 sysfs
686 0x012ff7b6 sysv2
687 0x012ff7b5 sysv4
688 0x01021994 tmpfs
689 0x15013346 udf
690 0x00011954 ufs
691 0x54190100 ufs byteswapped
692 0x00009fa2 usbdevfs
693 0x01021997 v9fs
694 0xa501fcf5 vxfs
695 0xabba1974 xenfs
696 0x012ff7b4 xenix
697 0x58465342 xfs
698 0x012fd16d xia
526 699
527=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 700=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
528 701
529Works like perl's C<utime> function (including the special case of $atime 702Works like perl's C<utime> function (including the special case of $atime
530and $mtime being undef). Fractional times are supported if the underlying 703and $mtime being undef). Fractional times are supported if the underlying
558=item aio_truncate $fh_or_path, $offset, $callback->($status) 731=item aio_truncate $fh_or_path, $offset, $callback->($status)
559 732
560Works like truncate(2) or ftruncate(2). 733Works like truncate(2) or ftruncate(2).
561 734
562 735
736=item aio_allocate $fh, $mode, $offset, $len, $callback->($status)
737
738Allocates or frees disk space according to the C<$mode> argument. See the
739linux C<fallocate> documentation for details.
740
741C<$mode> is usually C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> to allocate
742space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE>,
743to deallocate a file range.
744
745IO::AIO also supports C<FALLOC_FL_COLLAPSE_RANGE>, to remove a range
746(without leaving a hole), C<FALLOC_FL_ZERO_RANGE>, to zero a range,
747C<FALLOC_FL_INSERT_RANGE> to insert a range and C<FALLOC_FL_UNSHARE_RANGE>
748to unshare shared blocks (see your L<fallocate(2)> manpage).
749
750The file system block size used by C<fallocate> is presumably the
751C<f_bsize> returned by C<statvfs>, but different filesystems and filetypes
752can dictate other limitations.
753
754If C<fallocate> isn't available or cannot be emulated (currently no
755emulation will be attempted), passes C<-1> and sets C<$!> to C<ENOSYS>.
756
757
563=item aio_chmod $fh_or_path, $mode, $callback->($status) 758=item aio_chmod $fh_or_path, $mode, $callback->($status)
564 759
565Works like perl's C<chmod> function. 760Works like perl's C<chmod> function.
566 761
567 762
569 764
570Asynchronously unlink (delete) a file and call the callback with the 765Asynchronously unlink (delete) a file and call the callback with the
571result code. 766result code.
572 767
573 768
574=item aio_mknod $path, $mode, $dev, $callback->($status) 769=item aio_mknod $pathname, $mode, $dev, $callback->($status)
575 770
576[EXPERIMENTAL] 771[EXPERIMENTAL]
577 772
578Asynchronously create a device node (or fifo). See mknod(2). 773Asynchronously create a device node (or fifo). See mknod(2).
579 774
580The only (POSIX-) portable way of calling this function is: 775The only (POSIX-) portable way of calling this function is:
581 776
582 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 777 aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
583 778
779See C<aio_stat> for info about some potentially helpful extra constants
780and functions.
584 781
585=item aio_link $srcpath, $dstpath, $callback->($status) 782=item aio_link $srcpath, $dstpath, $callback->($status)
586 783
587Asynchronously create a new link to the existing object at C<$srcpath> at 784Asynchronously create a new link to the existing object at C<$srcpath> at
588the path C<$dstpath> and call the callback with the result code. 785the path C<$dstpath> and call the callback with the result code.
592 789
593Asynchronously create a new symbolic link to the existing object at C<$srcpath> at 790Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
594the path C<$dstpath> and call the callback with the result code. 791the path C<$dstpath> and call the callback with the result code.
595 792
596 793
597=item aio_readlink $path, $callback->($link) 794=item aio_readlink $pathname, $callback->($link)
598 795
599Asynchronously read the symlink specified by C<$path> and pass it to 796Asynchronously read the symlink specified by C<$path> and pass it to
600the callback. If an error occurs, nothing or undef gets passed to the 797the callback. If an error occurs, nothing or undef gets passed to the
601callback. 798callback.
602 799
603 800
801=item aio_realpath $pathname, $callback->($path)
802
803Asynchronously make the path absolute and resolve any symlinks in
804C<$path>. The resulting path only consists of directories (same as
805L<Cwd::realpath>).
806
807This request can be used to get the absolute path of the current working
808directory by passing it a path of F<.> (a single dot).
809
810
604=item aio_rename $srcpath, $dstpath, $callback->($status) 811=item aio_rename $srcpath, $dstpath, $callback->($status)
605 812
606Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 813Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
607rename(2) and call the callback with the result code. 814rename(2) and call the callback with the result code.
815
816On systems that support the AIO::WD working directory abstraction
817natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
818of failing, C<rename> is called on the absolute path of C<$wd>.
819
820
821=item aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
822
823Basically a version of C<aio_rename> with an additional C<$flags>
824argument. Calling this with C<$flags=0> is the same as calling
825C<aio_rename>.
826
827Non-zero flags are currently only supported on GNU/Linux systems that
828support renameat2. Other systems fail with C<ENOSYS> in this case.
829
830The following constants are available (missing ones are, as usual C<0>),
831see renameat2(2) for details:
832
833C<IO::AIO::RENAME_NOREPLACE>, C<IO::AIO::RENAME_EXCHANGE>
834and C<IO::AIO::RENAME_WHITEOUT>.
608 835
609 836
610=item aio_mkdir $pathname, $mode, $callback->($status) 837=item aio_mkdir $pathname, $mode, $callback->($status)
611 838
612Asynchronously mkdir (create) a directory and call the callback with 839Asynchronously mkdir (create) a directory and call the callback with
617=item aio_rmdir $pathname, $callback->($status) 844=item aio_rmdir $pathname, $callback->($status)
618 845
619Asynchronously rmdir (delete) a directory and call the callback with the 846Asynchronously rmdir (delete) a directory and call the callback with the
620result code. 847result code.
621 848
849On systems that support the AIO::WD working directory abstraction
850natively, the case C<[$wd, "."]> is specialcased - instead of failing,
851C<rmdir> is called on the absolute path of C<$wd>.
852
622 853
623=item aio_readdir $pathname, $callback->($entries) 854=item aio_readdir $pathname, $callback->($entries)
624 855
625Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 856Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
626directory (i.e. opendir + readdir + closedir). The entries will not be 857directory (i.e. opendir + readdir + closedir). The entries will not be
630array-ref with the filenames. 861array-ref with the filenames.
631 862
632 863
633=item aio_readdirx $pathname, $flags, $callback->($entries, $flags) 864=item aio_readdirx $pathname, $flags, $callback->($entries, $flags)
634 865
635Quite similar to C<aio_readdir>, but the C<$flags> argument allows to tune 866Quite similar to C<aio_readdir>, but the C<$flags> argument allows one to
636behaviour and output format. In case of an error, C<$entries> will be 867tune behaviour and output format. In case of an error, C<$entries> will be
637C<undef>. 868C<undef>.
638 869
639The flags are a combination of the following constants, ORed together (the 870The flags are a combination of the following constants, ORed together (the
640flags will also be passed to the callback, possibly modified): 871flags will also be passed to the callback, possibly modified):
641 872
642=over 4 873=over 4
643 874
644=item IO::AIO::READDIR_DENTS 875=item IO::AIO::READDIR_DENTS
645 876
646When this flag is off, then the callback gets an arrayref with of names 877When this flag is off, then the callback gets an arrayref consisting of
647only (as with C<aio_readdir>), otherwise it gets an arrayref with 878names only (as with C<aio_readdir>), otherwise it gets an arrayref with
648C<[$name, $type, $inode]> arrayrefs, each describing a single directory 879C<[$name, $type, $inode]> arrayrefs, each describing a single directory
649entry in more detail. 880entry in more detail.
650 881
651C<$name> is the name of the entry. 882C<$name> is the name of the entry.
652 883
665systems that do not deliver the inode information. 896systems that do not deliver the inode information.
666 897
667=item IO::AIO::READDIR_DIRS_FIRST 898=item IO::AIO::READDIR_DIRS_FIRST
668 899
669When this flag is set, then the names will be returned in an order where 900When this flag is set, then the names will be returned in an order where
670likely directories come first. This is useful when you need to quickly 901likely directories come first, in optimal stat order. This is useful when
671find directories, or you want to find all directories while avoiding to 902you need to quickly find directories, or you want to find all directories
672stat() each entry. 903while avoiding to stat() each entry.
673 904
674If the system returns type information in readdir, then this is used 905If the system returns type information in readdir, then this is used
675to find directories directly. Otherwise, likely directories are files 906to find directories directly. Otherwise, likely directories are names
676beginning with ".", or otherwise files with no dots, of which files with 907beginning with ".", or otherwise names with no dots, of which names with
677short names are tried first. 908short names are tried first.
678 909
679=item IO::AIO::READDIR_STAT_ORDER 910=item IO::AIO::READDIR_STAT_ORDER
680 911
681When this flag is set, then the names will be returned in an order 912When this flag is set, then the names will be returned in an order
688 919
689=item IO::AIO::READDIR_FOUND_UNKNOWN 920=item IO::AIO::READDIR_FOUND_UNKNOWN
690 921
691This flag should not be set when calling C<aio_readdirx>. Instead, it 922This flag should not be set when calling C<aio_readdirx>. Instead, it
692is being set by C<aio_readdirx>, when any of the C<$type>'s found were 923is being set by C<aio_readdirx>, when any of the C<$type>'s found were
693C<IO::AIO::DT_UNKNOWN>. The absense of this flag therefore indicates that all 924C<IO::AIO::DT_UNKNOWN>. The absence of this flag therefore indicates that all
694C<$type>'s are known, which can be used to speed up some algorithms. 925C<$type>'s are known, which can be used to speed up some algorithms.
695 926
696=back 927=back
697 928
698 929
699=item aio_load $path, $data, $callback->($status) 930=item aio_load $pathname, $data, $callback->($status)
700 931
701This is a composite request that tries to fully load the given file into 932This is a composite request that tries to fully load the given file into
702memory. Status is the same as with aio_read. 933memory. Status is the same as with aio_read.
703 934
704=cut 935=cut
727=item aio_copy $srcpath, $dstpath, $callback->($status) 958=item aio_copy $srcpath, $dstpath, $callback->($status)
728 959
729Try to copy the I<file> (directories not supported as either source or 960Try to copy the I<file> (directories not supported as either source or
730destination) from C<$srcpath> to C<$dstpath> and call the callback with 961destination) from C<$srcpath> to C<$dstpath> and call the callback with
731a status of C<0> (ok) or C<-1> (error, see C<$!>). 962a status of C<0> (ok) or C<-1> (error, see C<$!>).
963
964Existing destination files will be truncated.
732 965
733This is a composite request that creates the destination file with 966This is a composite request that creates the destination file with
734mode 0200 and copies the contents of the source file into it using 967mode 0200 and copies the contents of the source file into it using
735C<aio_sendfile>, followed by restoring atime, mtime, access mode and 968C<aio_sendfile>, followed by restoring atime, mtime, access mode and
736uid/gid, in that order. 969uid/gid, in that order.
826 if ($_[0] && $! == EXDEV) { 1059 if ($_[0] && $! == EXDEV) {
827 aioreq_pri $pri; 1060 aioreq_pri $pri;
828 add $grp aio_copy $src, $dst, sub { 1061 add $grp aio_copy $src, $dst, sub {
829 $grp->result ($_[0]); 1062 $grp->result ($_[0]);
830 1063
831 if (!$_[0]) { 1064 unless ($_[0]) {
832 aioreq_pri $pri; 1065 aioreq_pri $pri;
833 add $grp aio_unlink $src; 1066 add $grp aio_unlink $src;
834 } 1067 }
835 }; 1068 };
836 } else { 1069 } else {
839 }; 1072 };
840 1073
841 $grp 1074 $grp
842} 1075}
843 1076
844=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 1077=item aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
845 1078
846Scans a directory (similar to C<aio_readdir>) but additionally tries to 1079Scans a directory (similar to C<aio_readdir>) but additionally tries to
847efficiently separate the entries of directory C<$path> into two sets of 1080efficiently separate the entries of directory C<$path> into two sets of
848names, directories you can recurse into (directories), and ones you cannot 1081names, directories you can recurse into (directories), and ones you cannot
849recurse into (everything else, including symlinks to directories). 1082recurse into (everything else, including symlinks to directories).
880Then entries will be sorted into likely directories a non-initial dot 1113Then entries will be sorted into likely directories a non-initial dot
881currently) and likely non-directories (see C<aio_readdirx>). Then every 1114currently) and likely non-directories (see C<aio_readdirx>). Then every
882entry plus an appended C</.> will be C<stat>'ed, likely directories first, 1115entry plus an appended C</.> will be C<stat>'ed, likely directories first,
883in order of their inode numbers. If that succeeds, it assumes that the 1116in order of their inode numbers. If that succeeds, it assumes that the
884entry is a directory or a symlink to directory (which will be checked 1117entry is a directory or a symlink to directory (which will be checked
885seperately). This is often faster than stat'ing the entry itself because 1118separately). This is often faster than stat'ing the entry itself because
886filesystems might detect the type of the entry without reading the inode 1119filesystems might detect the type of the entry without reading the inode
887data (e.g. ext2fs filetype feature), even on systems that cannot return 1120data (e.g. ext2fs filetype feature), even on systems that cannot return
888the filetype information on readdir. 1121the filetype information on readdir.
889 1122
890If the known number of directories (link count - 2) has been reached, the 1123If the known number of directories (link count - 2) has been reached, the
906 1139
907 my $grp = aio_group $cb; 1140 my $grp = aio_group $cb;
908 1141
909 $maxreq = 4 if $maxreq <= 0; 1142 $maxreq = 4 if $maxreq <= 0;
910 1143
911 # stat once 1144 # get a wd object
912 aioreq_pri $pri; 1145 aioreq_pri $pri;
913 add $grp aio_stat $path, sub { 1146 add $grp aio_wd $path, sub {
1147 $_[0]
914 return $grp->result () if $_[0]; 1148 or return $grp->result ();
915 my $now = time;
916 my $hash1 = join ":", (stat _)[0,1,3,7,9];
917 1149
918 # read the directory entries 1150 my $wd = [shift, "."];
1151
1152 # stat once
919 aioreq_pri $pri; 1153 aioreq_pri $pri;
920 add $grp aio_readdirx $path, READDIR_DIRS_FIRST, sub { 1154 add $grp aio_stat $wd, sub {
921 my $entries = shift
922 or return $grp->result (); 1155 return $grp->result () if $_[0];
1156 my $now = time;
1157 my $hash1 = join ":", (stat _)[0,1,3,7,9];
923 1158
924 # stat the dir another time 1159 # read the directory entries
925 aioreq_pri $pri; 1160 aioreq_pri $pri;
1161 add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {
1162 my $entries = shift
1163 or return $grp->result ();
1164
1165 # stat the dir another time
1166 aioreq_pri $pri;
926 add $grp aio_stat $path, sub { 1167 add $grp aio_stat $wd, sub {
927 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 1168 my $hash2 = join ":", (stat _)[0,1,3,7,9];
928 1169
929 my $ndirs; 1170 my $ndirs;
930 1171
931 # take the slow route if anything looks fishy 1172 # take the slow route if anything looks fishy
932 if ($hash1 ne $hash2 or (stat _)[9] == $now) { 1173 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
933 $ndirs = -1; 1174 $ndirs = -1;
934 } else { 1175 } else {
935 # if nlink == 2, we are finished 1176 # if nlink == 2, we are finished
936 # for non-posix-fs's, we rely on nlink < 2 1177 # for non-posix-fs's, we rely on nlink < 2
937 $ndirs = (stat _)[3] - 2 1178 $ndirs = (stat _)[3] - 2
938 or return $grp->result ([], $entries); 1179 or return $grp->result ([], $entries);
939 } 1180 }
940 1181
941 my (@dirs, @nondirs); 1182 my (@dirs, @nondirs);
942 1183
943 my $statgrp = add $grp aio_group sub { 1184 my $statgrp = add $grp aio_group sub {
944 $grp->result (\@dirs, \@nondirs); 1185 $grp->result (\@dirs, \@nondirs);
945 }; 1186 };
946 1187
947 limit $statgrp $maxreq; 1188 limit $statgrp $maxreq;
948 feed $statgrp sub { 1189 feed $statgrp sub {
949 return unless @$entries; 1190 return unless @$entries;
950 my $entry = shift @$entries; 1191 my $entry = shift @$entries;
951 1192
952 aioreq_pri $pri; 1193 aioreq_pri $pri;
1194 $wd->[1] = "$entry/.";
953 add $statgrp aio_stat "$path/$entry/.", sub { 1195 add $statgrp aio_stat $wd, sub {
954 if ($_[0] < 0) { 1196 if ($_[0] < 0) {
955 push @nondirs, $entry; 1197 push @nondirs, $entry;
956 } else { 1198 } else {
957 # need to check for real directory 1199 # need to check for real directory
958 aioreq_pri $pri; 1200 aioreq_pri $pri;
1201 $wd->[1] = $entry;
959 add $statgrp aio_lstat "$path/$entry", sub { 1202 add $statgrp aio_lstat $wd, sub {
960 if (-d _) { 1203 if (-d _) {
961 push @dirs, $entry; 1204 push @dirs, $entry;
962 1205
963 unless (--$ndirs) { 1206 unless (--$ndirs) {
964 push @nondirs, @$entries; 1207 push @nondirs, @$entries;
965 feed $statgrp; 1208 feed $statgrp;
1209 }
1210 } else {
1211 push @nondirs, $entry;
966 } 1212 }
967 } else {
968 push @nondirs, $entry;
969 } 1213 }
970 } 1214 }
971 } 1215 };
972 }; 1216 };
973 }; 1217 };
974 }; 1218 };
975 }; 1219 };
976 }; 1220 };
977 1221
978 $grp 1222 $grp
979} 1223}
980 1224
981=item aio_rmtree $path, $callback->($status) 1225=item aio_rmtree $pathname, $callback->($status)
982 1226
983Delete a directory tree starting (and including) C<$path>, return the 1227Delete a directory tree starting (and including) C<$path>, return the
984status of the final C<rmdir> only. This is a composite request that 1228status of the final C<rmdir> only. This is a composite request that
985uses C<aio_scandir> to recurse into and rmdir directories, and unlink 1229uses C<aio_scandir> to recurse into and rmdir directories, and unlink
986everything else. 1230everything else.
987 1231
988=cut 1232=cut
989 1233
1011 }; 1255 };
1012 1256
1013 $grp 1257 $grp
1014} 1258}
1015 1259
1260=item aio_fcntl $fh, $cmd, $arg, $callback->($status)
1261
1262=item aio_ioctl $fh, $request, $buf, $callback->($status)
1263
1264These work just like the C<fcntl> and C<ioctl> built-in functions, except
1265they execute asynchronously and pass the return value to the callback.
1266
1267Both calls can be used for a lot of things, some of which make more sense
1268to run asynchronously in their own thread, while some others make less
1269sense. For example, calls that block waiting for external events, such
1270as locking, will also lock down an I/O thread while it is waiting, which
1271can deadlock the whole I/O system. At the same time, there might be no
1272alternative to using a thread to wait.
1273
1274So in general, you should only use these calls for things that do
1275(filesystem) I/O, not for things that wait for other events (network,
1276other processes), although if you are careful and know what you are doing,
1277you still can.
1278
1279The following constants are available (missing ones are, as usual C<0>):
1280
1281C<F_DUPFD_CLOEXEC>,
1282
1283C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
1284
1285C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
1286
1287C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1288C<FS_IOC_FIEMAP>.
1289
1290C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
1291C<FS_IOC_GET_ENCRYPTION_PWSALT>, C<FS_IOC_GET_ENCRYPTION_POLICY>, C<FS_KEY_DESCRIPTOR_SIZE>.
1292
1293C<FS_SECRM_FL>, C<FS_UNRM_FL>, C<FS_COMPR_FL>, C<FS_SYNC_FL>, C<FS_IMMUTABLE_FL>,
1294C<FS_APPEND_FL>, C<FS_NODUMP_FL>, C<FS_NOATIME_FL>, C<FS_DIRTY_FL>,
1295C<FS_COMPRBLK_FL>, C<FS_NOCOMP_FL>, C<FS_ENCRYPT_FL>, C<FS_BTREE_FL>,
1296C<FS_INDEX_FL>, C<FS_JOURNAL_DATA_FL>, C<FS_NOTAIL_FL>, C<FS_DIRSYNC_FL>, C<FS_TOPDIR_FL>,
1297C<FS_FL_USER_MODIFIABLE>.
1298
1299C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1300C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1301C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1302C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
1303
1016=item aio_sync $callback->($status) 1304=item aio_sync $callback->($status)
1017 1305
1018Asynchronously call sync and call the callback when finished. 1306Asynchronously call sync and call the callback when finished.
1019 1307
1020=item aio_fsync $fh, $callback->($status) 1308=item aio_fsync $fh, $callback->($status)
1027Asynchronously call fdatasync on the given filehandle and call the 1315Asynchronously call fdatasync on the given filehandle and call the
1028callback with the fdatasync result code. 1316callback with the fdatasync result code.
1029 1317
1030If this call isn't available because your OS lacks it or it couldn't be 1318If this call isn't available because your OS lacks it or it couldn't be
1031detected, it will be emulated by calling C<fsync> instead. 1319detected, it will be emulated by calling C<fsync> instead.
1320
1321=item aio_syncfs $fh, $callback->($status)
1322
1323Asynchronously call the syncfs syscall to sync the filesystem associated
1324to the given filehandle and call the callback with the syncfs result
1325code. If syncfs is not available, calls sync(), but returns C<-1> and sets
1326errno to C<ENOSYS> nevertheless.
1032 1327
1033=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 1328=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
1034 1329
1035Sync the data portion of the file specified by C<$offset> and C<$length> 1330Sync the data portion of the file specified by C<$offset> and C<$length>
1036to disk (but NOT the metadata), by calling the Linux-specific 1331to disk (but NOT the metadata), by calling the Linux-specific
1040C<$flags> can be a combination of C<IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE>, 1335C<$flags> can be a combination of C<IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE>,
1041C<IO::AIO::SYNC_FILE_RANGE_WRITE> and 1336C<IO::AIO::SYNC_FILE_RANGE_WRITE> and
1042C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range 1337C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range
1043manpage for details. 1338manpage for details.
1044 1339
1045=item aio_pathsync $path, $callback->($status) 1340=item aio_pathsync $pathname, $callback->($status)
1046 1341
1047This request tries to open, fsync and close the given path. This is a 1342This request tries to open, fsync and close the given path. This is a
1048composite request intended to sync directories after directory operations 1343composite request intended to sync directories after directory operations
1049(E.g. rename). This might not work on all operating systems or have any 1344(E.g. rename). This might not work on all operating systems or have any
1050specific effect, but usually it makes sure that directory changes get 1345specific effect, but usually it makes sure that directory changes get
1081 }; 1376 };
1082 1377
1083 $grp 1378 $grp
1084} 1379}
1085 1380
1086=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1381=item aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
1087 1382
1088This is a rather advanced IO::AIO call, which only works on mmap(2)ed 1383This is a rather advanced IO::AIO call, which only works on mmap(2)ed
1089scalars (see the C<IO::AIO::mmap> function, although it also works on data 1384scalars (see the C<IO::AIO::mmap> function, although it also works on data
1090scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the 1385scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the
1091scalar must only be modified in-place while an aio operation is pending on 1386scalar must only be modified in-place while an aio operation is pending on
1093 1388
1094It calls the C<msync> function of your OS, if available, with the memory 1389It calls the C<msync> function of your OS, if available, with the memory
1095area starting at C<$offset> in the string and ending C<$length> bytes 1390area starting at C<$offset> in the string and ending C<$length> bytes
1096later. If C<$length> is negative, counts from the end, and if C<$length> 1391later. If C<$length> is negative, counts from the end, and if C<$length>
1097is C<undef>, then it goes till the end of the string. The flags can be 1392is C<undef>, then it goes till the end of the string. The flags can be
1098a combination of C<IO::AIO::MS_ASYNC>, C<IO::AIO::MS_INVALIDATE> and 1393either C<IO::AIO::MS_ASYNC> or C<IO::AIO::MS_SYNC>, plus an optional
1099C<IO::AIO::MS_SYNC>. 1394C<IO::AIO::MS_INVALIDATE>.
1100 1395
1101=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1396=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1102 1397
1103This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1398This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1104scalars. 1399scalars.
1105 1400
1106It touches (reads or writes) all memory pages in the specified 1401It touches (reads or writes) all memory pages in the specified
1107range inside the scalar. All caveats and parameters are the same 1402range inside the scalar. All caveats and parameters are the same
1108as for C<aio_msync>, above, except for flags, which must be either 1403as for C<aio_msync>, above, except for flags, which must be either
1109C<0> (which reads all pages and ensures they are instantiated) or 1404C<0> (which reads all pages and ensures they are instantiated) or
1110C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and 1405C<IO::AIO::MT_MODIFY>, which modifies the memory pages (by reading and
1111writing an octet from it, which dirties the page). 1406writing an octet from it, which dirties the page).
1407
1408=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1409
1410This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1411scalars.
1412
1413It reads in all the pages of the underlying storage into memory (if any)
1414and locks them, so they are not getting swapped/paged out or removed.
1415
1416If C<$length> is undefined, then the scalar will be locked till the end.
1417
1418On systems that do not implement C<mlock>, this function returns C<-1>
1419and sets errno to C<ENOSYS>.
1420
1421Note that the corresponding C<munlock> is synchronous and is
1422documented under L<MISCELLANEOUS FUNCTIONS>.
1423
1424Example: open a file, mmap and mlock it - both will be undone when
1425C<$data> gets destroyed.
1426
1427 open my $fh, "<", $path or die "$path: $!";
1428 my $data;
1429 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1430 aio_mlock $data; # mlock in background
1431
1432=item aio_mlockall $flags, $callback->($status)
1433
1434Calls the C<mlockall> function with the given C<$flags> (a combination of
1435C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
1436
1437On systems that do not implement C<mlockall>, this function returns C<-1>
1438and sets errno to C<ENOSYS>.
1439
1440Note that the corresponding C<munlockall> is synchronous and is
1441documented under L<MISCELLANEOUS FUNCTIONS>.
1442
1443Example: asynchronously lock all current and future pages into memory.
1444
1445 aio_mlockall IO::AIO::MCL_FUTURE;
1446
1447=item aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1448
1449Queries the extents of the given file (by calling the Linux C<FIEMAP>
1450ioctl, see L<http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for details). If
1451the ioctl is not available on your OS, then this request will fail with
1452C<ENOSYS>.
1453
1454C<$start> is the starting offset to query extents for, C<$length> is the
1455size of the range to query - if it is C<undef>, then the whole file will
1456be queried.
1457
1458C<$flags> is a combination of flags (C<IO::AIO::FIEMAP_FLAG_SYNC> or
1459C<IO::AIO::FIEMAP_FLAG_XATTR> - C<IO::AIO::FIEMAP_FLAGS_COMPAT> is also
1460exported), and is normally C<0> or C<IO::AIO::FIEMAP_FLAG_SYNC> to query
1461the data portion.
1462
1463C<$count> is the maximum number of extent records to return. If it is
1464C<undef>, then IO::AIO queries all extents of the range. As a very special
1465case, if it is C<0>, then the callback receives the number of extents
1466instead of the extents themselves (which is unreliable, see below).
1467
1468If an error occurs, the callback receives no arguments. The special
1469C<errno> value C<IO::AIO::EBADR> is available to test for flag errors.
1470
1471Otherwise, the callback receives an array reference with extent
1472structures. Each extent structure is an array reference itself, with the
1473following members:
1474
1475 [$logical, $physical, $length, $flags]
1476
1477Flags is any combination of the following flag values (typically either C<0>
1478or C<IO::AIO::FIEMAP_EXTENT_LAST> (1)):
1479
1480C<IO::AIO::FIEMAP_EXTENT_LAST>, C<IO::AIO::FIEMAP_EXTENT_UNKNOWN>,
1481C<IO::AIO::FIEMAP_EXTENT_DELALLOC>, C<IO::AIO::FIEMAP_EXTENT_ENCODED>,
1482C<IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED>, C<IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED>,
1483C<IO::AIO::FIEMAP_EXTENT_DATA_INLINE>, C<IO::AIO::FIEMAP_EXTENT_DATA_TAIL>,
1484C<IO::AIO::FIEMAP_EXTENT_UNWRITTEN>, C<IO::AIO::FIEMAP_EXTENT_MERGED> or
1485C<IO::AIO::FIEMAP_EXTENT_SHARED>.
1486
1487At the time of this writing (Linux 3.2), this requets is unreliable unless
1488C<$count> is C<undef>, as the kernel has all sorts of bugs preventing
1489it to return all extents of a range for files with large number of
1490extents. The code works around all these issues if C<$count> is undef.
1112 1491
1113=item aio_group $callback->(...) 1492=item aio_group $callback->(...)
1114 1493
1115This is a very special aio request: Instead of doing something, it is a 1494This is a very special aio request: Instead of doing something, it is a
1116container for other aio requests, which is useful if you want to bundle 1495container for other aio requests, which is useful if you want to bundle
1153like sleep and file handle readable/writable, the overhead this creates is 1532like sleep and file handle readable/writable, the overhead this creates is
1154immense (it blocks a thread for a long time) so do not use this function 1533immense (it blocks a thread for a long time) so do not use this function
1155except to put your application under artificial I/O pressure. 1534except to put your application under artificial I/O pressure.
1156 1535
1157=back 1536=back
1537
1538
1539=head2 IO::AIO::WD - multiple working directories
1540
1541Your process only has one current working directory, which is used by all
1542threads. This makes it hard to use relative paths (some other component
1543could call C<chdir> at any time, and it is hard to control when the path
1544will be used by IO::AIO).
1545
1546One solution for this is to always use absolute paths. This usually works,
1547but can be quite slow (the kernel has to walk the whole path on every
1548access), and can also be a hassle to implement.
1549
1550Newer POSIX systems have a number of functions (openat, fdopendir,
1551futimensat and so on) that make it possible to specify working directories
1552per operation.
1553
1554For portability, and because the clowns who "designed", or shall I write,
1555perpetrated this new interface were obviously half-drunk, this abstraction
1556cannot be perfect, though.
1557
1558IO::AIO allows you to convert directory paths into a so-called IO::AIO::WD
1559object. This object stores the canonicalised, absolute version of the
1560path, and on systems that allow it, also a directory file descriptor.
1561
1562Everywhere where a pathname is accepted by IO::AIO (e.g. in C<aio_stat>
1563or C<aio_unlink>), one can specify an array reference with an IO::AIO::WD
1564object and a pathname instead (or the IO::AIO::WD object alone, which
1565gets interpreted as C<[$wd, "."]>). If the pathname is absolute, the
1566IO::AIO::WD object is ignored, otherwise the pathname is resolved relative
1567to that IO::AIO::WD object.
1568
1569For example, to get a wd object for F</etc> and then stat F<passwd>
1570inside, you would write:
1571
1572 aio_wd "/etc", sub {
1573 my $etcdir = shift;
1574
1575 # although $etcdir can be undef on error, there is generally no reason
1576 # to check for errors here, as aio_stat will fail with ENOENT
1577 # when $etcdir is undef.
1578
1579 aio_stat [$etcdir, "passwd"], sub {
1580 # yay
1581 };
1582 };
1583
1584The fact that C<aio_wd> is a request and not a normal function shows that
1585creating an IO::AIO::WD object is itself a potentially blocking operation,
1586which is why it is done asynchronously.
1587
1588To stat the directory obtained with C<aio_wd> above, one could write
1589either of the following three request calls:
1590
1591 aio_lstat "/etc" , sub { ... # pathname as normal string
1592 aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
1593 aio_lstat $wd , sub { ... # shorthand for the previous
1594
1595As with normal pathnames, IO::AIO keeps a copy of the working directory
1596object and the pathname string, so you could write the following without
1597causing any issues due to C<$path> getting reused:
1598
1599 my $path = [$wd, undef];
1600
1601 for my $name (qw(abc def ghi)) {
1602 $path->[1] = $name;
1603 aio_stat $path, sub {
1604 # ...
1605 };
1606 }
1607
1608There are some caveats: when directories get renamed (or deleted), the
1609pathname string doesn't change, so will point to the new directory (or
1610nowhere at all), while the directory fd, if available on the system,
1611will still point to the original directory. Most functions accepting a
1612pathname will use the directory fd on newer systems, and the string on
1613older systems. Some functions (such as realpath) will always rely on the
1614string form of the pathname.
1615
1616So this functionality is mainly useful to get some protection against
1617C<chdir>, to easily get an absolute path out of a relative path for future
1618reference, and to speed up doing many operations in the same directory
1619(e.g. when stat'ing all files in a directory).
1620
1621The following functions implement this working directory abstraction:
1622
1623=over 4
1624
1625=item aio_wd $pathname, $callback->($wd)
1626
1627Asynchonously canonicalise the given pathname and convert it to an
1628IO::AIO::WD object representing it. If possible and supported on the
1629system, also open a directory fd to speed up pathname resolution relative
1630to this working directory.
1631
1632If something goes wrong, then C<undef> is passwd to the callback instead
1633of a working directory object and C<$!> is set appropriately. Since
1634passing C<undef> as working directory component of a pathname fails the
1635request with C<ENOENT>, there is often no need for error checking in the
1636C<aio_wd> callback, as future requests using the value will fail in the
1637expected way.
1638
1639=item IO::AIO::CWD
1640
1641This is a compiletime constant (object) that represents the process
1642current working directory.
1643
1644Specifying this object as working directory object for a pathname is as if
1645the pathname would be specified directly, without a directory object. For
1646example, these calls are functionally identical:
1647
1648 aio_stat "somefile", sub { ... };
1649 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1650
1651=back
1652
1653To recover the path associated with an IO::AIO::WD object, you can use
1654C<aio_realpath>:
1655
1656 aio_realpath $wd, sub {
1657 warn "path is $_[0]\n";
1658 };
1659
1660Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
1661sometimes, fall back to using an absolue path.
1158 1662
1159=head2 IO::AIO::REQ CLASS 1663=head2 IO::AIO::REQ CLASS
1160 1664
1161All non-aggregate C<aio_*> functions return an object of this class when 1665All non-aggregate C<aio_*> functions return an object of this class when
1162called in non-void context. 1666called in non-void context.
1280 1784
1281Sets a feeder/generator on this group: every group can have an attached 1785Sets a feeder/generator on this group: every group can have an attached
1282generator that generates requests if idle. The idea behind this is that, 1786generator that generates requests if idle. The idea behind this is that,
1283although you could just queue as many requests as you want in a group, 1787although you could just queue as many requests as you want in a group,
1284this might starve other requests for a potentially long time. For example, 1788this might starve other requests for a potentially long time. For example,
1285C<aio_scandir> might generate hundreds of thousands C<aio_stat> requests, 1789C<aio_scandir> might generate hundreds of thousands of C<aio_stat>
1286delaying any later requests for a long time. 1790requests, delaying any later requests for a long time.
1287 1791
1288To avoid this, and allow incremental generation of requests, you can 1792To avoid this, and allow incremental generation of requests, you can
1289instead a group and set a feeder on it that generates those requests. The 1793instead a group and set a feeder on it that generates those requests. The
1290feed callback will be called whenever there are few enough (see C<limit>, 1794feed callback will be called whenever there are few enough (see C<limit>,
1291below) requests active in the group itself and is expected to queue more 1795below) requests active in the group itself and is expected to queue more
1340 1844
1341See C<poll_cb> for an example. 1845See C<poll_cb> for an example.
1342 1846
1343=item IO::AIO::poll_cb 1847=item IO::AIO::poll_cb
1344 1848
1345Process some outstanding events on the result pipe. You have to call this 1849Process some requests that have reached the result phase (i.e. they have
1346regularly. Returns C<0> if all events could be processed, or C<-1> if it 1850been executed but the results are not yet reported). You have to call
1347returned earlier for whatever reason. Returns immediately when no events 1851this "regularly" to finish outstanding requests.
1348are outstanding. The amount of events processed depends on the settings of
1349C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
1350 1852
1853Returns C<0> if all events could be processed (or there were no
1854events to process), or C<-1> if it returned earlier for whatever
1855reason. Returns immediately when no events are outstanding. The amount
1856of events processed depends on the settings of C<IO::AIO::max_poll_req>,
1857C<IO::AIO::max_poll_time> and C<IO::AIO::max_outstanding>.
1858
1351If not all requests were processed for whatever reason, the filehandle 1859If not all requests were processed for whatever reason, the poll file
1352will still be ready when C<poll_cb> returns, so normally you don't have to 1860descriptor will still be ready when C<poll_cb> returns, so normally you
1353do anything special to have it called later. 1861don't have to do anything special to have it called later.
1862
1863Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
1864ready, it can be beneficial to call this function from loops which submit
1865a lot of requests, to make sure the results get processed when they become
1866available and not just when the loop is finished and the event loop takes
1867over again. This function returns very fast when there are no outstanding
1868requests.
1354 1869
1355Example: Install an Event watcher that automatically calls 1870Example: Install an Event watcher that automatically calls
1356IO::AIO::poll_cb with high priority (more examples can be found in the 1871IO::AIO::poll_cb with high priority (more examples can be found in the
1357SYNOPSIS section, at the top of this document): 1872SYNOPSIS section, at the top of this document):
1358 1873
1360 poll => 'r', async => 1, 1875 poll => 'r', async => 1,
1361 cb => \&IO::AIO::poll_cb); 1876 cb => \&IO::AIO::poll_cb);
1362 1877
1363=item IO::AIO::poll_wait 1878=item IO::AIO::poll_wait
1364 1879
1365If there are any outstanding requests and none of them in the result 1880Wait until either at least one request is in the result phase or no
1366phase, wait till the result filehandle becomes ready for reading (simply 1881requests are outstanding anymore.
1367does a C<select> on the filehandle. This is useful if you want to 1882
1368synchronously wait for some requests to finish). 1883This is useful if you want to synchronously wait for some requests to
1884become ready, without actually handling them.
1369 1885
1370See C<nreqs> for an example. 1886See C<nreqs> for an example.
1371 1887
1372=item IO::AIO::poll 1888=item IO::AIO::poll
1373 1889
1460 1976
1461Under normal circumstances you don't need to call this function. 1977Under normal circumstances you don't need to call this function.
1462 1978
1463=item IO::AIO::max_idle $nthreads 1979=item IO::AIO::max_idle $nthreads
1464 1980
1465Limit the number of threads (default: 4) that are allowed to idle (i.e., 1981Limit the number of threads (default: 4) that are allowed to idle
1466threads that did not get a request to process within 10 seconds). That 1982(i.e., threads that did not get a request to process within the idle
1467means if a thread becomes idle while C<$nthreads> other threads are also 1983timeout (default: 10 seconds). That means if a thread becomes idle while
1468idle, it will free its resources and exit. 1984C<$nthreads> other threads are also idle, it will free its resources and
1985exit.
1469 1986
1470This is useful when you allow a large number of threads (e.g. 100 or 1000) 1987This is useful when you allow a large number of threads (e.g. 100 or 1000)
1471to allow for extremely high load situations, but want to free resources 1988to allow for extremely high load situations, but want to free resources
1472under normal circumstances (1000 threads can easily consume 30MB of RAM). 1989under normal circumstances (1000 threads can easily consume 30MB of RAM).
1473 1990
1474The default is probably ok in most situations, especially if thread 1991The default is probably ok in most situations, especially if thread
1475creation is fast. If thread creation is very slow on your system you might 1992creation is fast. If thread creation is very slow on your system you might
1476want to use larger values. 1993want to use larger values.
1477 1994
1995=item IO::AIO::idle_timeout $seconds
1996
1997Sets the minimum idle timeout (default 10) after which worker threads are
1998allowed to exit. SEe C<IO::AIO::max_idle>.
1999
1478=item IO::AIO::max_outstanding $maxreqs 2000=item IO::AIO::max_outstanding $maxreqs
2001
2002Sets the maximum number of outstanding requests to C<$nreqs>. If
2003you do queue up more than this number of requests, the next call to
2004C<IO::AIO::poll_cb> (and other functions calling C<poll_cb>, such as
2005C<IO::AIO::flush> or C<IO::AIO::poll>) will block until the limit is no
2006longer exceeded.
2007
2008In other words, this setting does not enforce a queue limit, but can be
2009used to make poll functions block if the limit is exceeded.
1479 2010
1480This is a very bad function to use in interactive programs because it 2011This is a very bad function to use in interactive programs because it
1481blocks, and a bad way to reduce concurrency because it is inexact: Better 2012blocks, and a bad way to reduce concurrency because it is inexact: Better
1482use an C<aio_group> together with a feed callback. 2013use an C<aio_group> together with a feed callback.
1483 2014
1484Sets the maximum number of outstanding requests to C<$nreqs>. If you 2015Its main use is in scripts without an event loop - when you want to stat
1485do queue up more than this number of requests, the next call to the 2016a lot of files, you can write something like this:
1486C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
1487function will block until the limit is no longer exceeded.
1488 2017
1489The default value is very large, so there is no practical limit on the 2018 IO::AIO::max_outstanding 32;
1490number of outstanding requests.
1491 2019
1492You can still queue as many requests as you want. Therefore, 2020 for my $path (...) {
1493C<max_outstanding> is mainly useful in simple scripts (with low values) or 2021 aio_stat $path , ...;
1494as a stop gap to shield against fatal memory overflow (with large values). 2022 IO::AIO::poll_cb;
2023 }
2024
2025 IO::AIO::flush;
2026
2027The call to C<poll_cb> inside the loop will normally return instantly, but
2028as soon as more thna C<32> reqeusts are in-flight, it will block until
2029some requests have been handled. This keeps the loop from pushing a large
2030number of C<aio_stat> requests onto the queue.
2031
2032The default value for C<max_outstanding> is very large, so there is no
2033practical limit on the number of outstanding requests.
1495 2034
1496=back 2035=back
1497 2036
1498=head3 STATISTICAL INFORMATION 2037=head3 STATISTICAL INFORMATION
1499 2038
1521 2060
1522=back 2061=back
1523 2062
1524=head3 MISCELLANEOUS FUNCTIONS 2063=head3 MISCELLANEOUS FUNCTIONS
1525 2064
1526IO::AIO implements some functions that might be useful, but are not 2065IO::AIO implements some functions that are useful when you want to use
1527asynchronous. 2066some "Advanced I/O" function not available to in Perl, without going the
2067"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
2068counterpart.
1528 2069
1529=over 4 2070=over 4
2071
2072=item $numfd = IO::AIO::get_fdlimit
2073
2074Tries to find the current file descriptor limit and returns it, or
2075C<undef> and sets C<$!> in case of an error. The limit is one larger than
2076the highest valid file descriptor number.
2077
2078=item IO::AIO::min_fdlimit [$numfd]
2079
2080Try to increase the current file descriptor limit(s) to at least C<$numfd>
2081by changing the soft or hard file descriptor resource limit. If C<$numfd>
2082is missing, it will try to set a very high limit, although this is not
2083recommended when you know the actual minimum that you require.
2084
2085If the limit cannot be raised enough, the function makes a best-effort
2086attempt to increase the limit as much as possible, using various
2087tricks, while still failing. You can query the resulting limit using
2088C<IO::AIO::get_fdlimit>.
2089
2090If an error occurs, returns C<undef> and sets C<$!>.
1530 2091
1531=item IO::AIO::sendfile $ofh, $ifh, $offset, $count 2092=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1532 2093
1533Calls the C<eio_sendfile_sync> function, which is like C<aio_sendfile>, 2094Calls the C<eio_sendfile_sync> function, which is like C<aio_sendfile>,
1534but is blocking (this makes most sense if you know the input data is 2095but is blocking (this makes most sense if you know the input data is
1537 2098
1538Returns the number of bytes copied, or C<-1> on error. 2099Returns the number of bytes copied, or C<-1> on error.
1539 2100
1540=item IO::AIO::fadvise $fh, $offset, $len, $advice 2101=item IO::AIO::fadvise $fh, $offset, $len, $advice
1541 2102
1542Simply calls the C<posix_fadvise> function (see it's 2103Simply calls the C<posix_fadvise> function (see its
1543manpage for details). The following advice constants are 2104manpage for details). The following advice constants are
1544avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>, 2105available: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1545C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>, 2106C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1546C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 2107C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1547 2108
1548On systems that do not implement C<posix_fadvise>, this function returns 2109On systems that do not implement C<posix_fadvise>, this function returns
1549ENOSYS, otherwise the return value of C<posix_fadvise>. 2110ENOSYS, otherwise the return value of C<posix_fadvise>.
1550 2111
2112=item IO::AIO::madvise $scalar, $offset, $len, $advice
2113
2114Simply calls the C<posix_madvise> function (see its
2115manpage for details). The following advice constants are
2116available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
2117C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>,
2118C<IO::AIO::MADV_DONTNEED>.
2119
2120If C<$offset> is negative, counts from the end. If C<$length> is negative,
2121the remaining length of the C<$scalar> is used. If possible, C<$length>
2122will be reduced to fit into the C<$scalar>.
2123
2124On systems that do not implement C<posix_madvise>, this function returns
2125ENOSYS, otherwise the return value of C<posix_madvise>.
2126
2127=item IO::AIO::mprotect $scalar, $offset, $len, $protect
2128
2129Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
2130$scalar (see its manpage for details). The following protect
2131constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
2132C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
2133
2134If C<$offset> is negative, counts from the end. If C<$length> is negative,
2135the remaining length of the C<$scalar> is used. If possible, C<$length>
2136will be reduced to fit into the C<$scalar>.
2137
2138On systems that do not implement C<mprotect>, this function returns
2139ENOSYS, otherwise the return value of C<mprotect>.
2140
1551=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 2141=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1552 2142
1553Memory-maps a file (or anonymous memory range) and attaches it to the 2143Memory-maps a file (or anonymous memory range) and attaches it to the
1554given C<$scalar>, which will act like a string scalar. 2144given C<$scalar>, which will act like a string scalar. Returns true on
2145success, and false otherwise.
1555 2146
2147The scalar must exist, but its contents do not matter - this means you
2148cannot use a nonexistant array or hash element. When in doubt, C<undef>
2149the scalar first.
2150
1556The only operations allowed on the scalar are C<substr>/C<vec> that don't 2151The only operations allowed on the mmapped scalar are C<substr>/C<vec>,
1557change the string length, and most read-only operations such as copying it 2152which don't change the string length, and most read-only operations such
1558or searching it with regexes and so on. 2153as copying it or searching it with regexes and so on.
1559 2154
1560Anything else is unsafe and will, at best, result in memory leaks. 2155Anything else is unsafe and will, at best, result in memory leaks.
1561 2156
1562The memory map associated with the C<$scalar> is automatically removed 2157The memory map associated with the C<$scalar> is automatically removed
1563when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or 2158when the C<$scalar> is undef'd or destroyed, or when the C<IO::AIO::mmap>
1564C<IO::AIO::munmap> functions are called. 2159or C<IO::AIO::munmap> functions are called on it.
1565 2160
1566This calls the C<mmap>(2) function internally. See your system's manual 2161This calls the C<mmap>(2) function internally. See your system's manual
1567page for details on the C<$length>, C<$prot> and C<$flags> parameters. 2162page for details on the C<$length>, C<$prot> and C<$flags> parameters.
1568 2163
1569The C<$length> must be larger than zero and smaller than the actual 2164The C<$length> must be larger than zero and smaller than the actual
1570filesize. 2165filesize.
1571 2166
1572C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>, 2167C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>,
1573C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>, 2168C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
1574 2169
1575C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or 2170C<$flags> can be a combination of
1576C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when 2171C<IO::AIO::MAP_SHARED> or
1577not available, the are defined as 0): C<IO::AIO::MAP_ANONYMOUS> 2172C<IO::AIO::MAP_PRIVATE>,
2173or a number of system-specific flags (when not available, the are C<0>):
1578(which is set to C<MAP_ANON> if your system only provides this 2174C<IO::AIO::MAP_ANONYMOUS> (which is set to C<MAP_ANON> if your system only provides this constant),
1579constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>, 2175C<IO::AIO::MAP_LOCKED>,
1580C<IO::AIO::MAP_NORESERVE>, C<IO::AIO::MAP_POPULATE> or 2176C<IO::AIO::MAP_NORESERVE>,
2177C<IO::AIO::MAP_POPULATE>,
1581C<IO::AIO::MAP_NONBLOCK> 2178C<IO::AIO::MAP_NONBLOCK>,
2179C<IO::AIO::MAP_FIXED>,
2180C<IO::AIO::MAP_GROWSDOWN>,
2181C<IO::AIO::MAP_32BIT>,
2182C<IO::AIO::MAP_HUGETLB> or
2183C<IO::AIO::MAP_STACK>.
1582 2184
1583If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. 2185If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
1584 2186
2187C<$offset> is the offset from the start of the file - it generally must be
2188a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
2189
2190Example:
2191
2192 use Digest::MD5;
2193 use IO::AIO;
2194
2195 open my $fh, "<verybigfile"
2196 or die "$!";
2197
2198 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
2199 or die "verybigfile: $!";
2200
2201 my $fast_md5 = md5 $data;
2202
1585=item IO::AIO::munmap $scalar 2203=item IO::AIO::munmap $scalar
1586 2204
1587Removes a previous mmap and undefines the C<$scalar>. 2205Removes a previous mmap and undefines the C<$scalar>.
1588 2206
1589=item IO::AIO::mlockall $flags 2207=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
1590 2208
1591Calls the C<mlockall> function with the given C<$flags> (a combination of 2209Calls the C<munlock> function, undoing the effects of a previous
1592C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL__FUTURE>). 2210C<aio_mlock> call (see its description for details).
1593
1594On systems that do not implement C<mlockall>, this function returns
1595ENOSYS, otherwise the return value of C<mlockall>.
1596 2211
1597=item IO::AIO::munlockall 2212=item IO::AIO::munlockall
1598 2213
1599Calls the C<munlockall> function. 2214Calls the C<munlockall> function.
1600 2215
1601On systems that do not implement C<munlockall>, this function returns 2216On systems that do not implement C<munlockall>, this function returns
1602ENOSYS, otherwise the return value of C<munlockall>. 2217ENOSYS, otherwise the return value of C<munlockall>.
2218
2219=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
2220
2221Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
2222C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
2223should be the file offset.
2224
2225C<$r_fh> and C<$w_fh> should not refer to the same file, as splice might
2226silently corrupt the data in this case.
2227
2228The following symbol flag values are available: C<IO::AIO::SPLICE_F_MOVE>,
2229C<IO::AIO::SPLICE_F_NONBLOCK>, C<IO::AIO::SPLICE_F_MORE> and
2230C<IO::AIO::SPLICE_F_GIFT>.
2231
2232See the C<splice(2)> manpage for details.
2233
2234=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2235
2236Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
2237description for C<IO::AIO::splice> above for details.
2238
2239=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2240
2241Attempts to query or change the pipe buffer size. Obviously works only
2242on pipes, and currently works only on GNU/Linux systems, and fails with
2243C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2244size on other systems, drop me a note.
2245
2246=item ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
2247
2248This is a direct interface to the Linux L<pipe2(2)> system call. If
2249C<$flags> is missing or C<0>, then this should be the same as a call to
2250perl's built-in C<pipe> function and create a new pipe, and works on
2251systems that lack the pipe2 syscall. On win32, this case invokes C<_pipe
2252(..., 4096, O_BINARY)>.
2253
2254If C<$flags> is non-zero, it tries to invoke the pipe2 system call with
2255the given flags (Linux 2.6.27, glibc 2.9).
2256
2257On success, the read and write file handles are returned.
2258
2259On error, nothing will be returned. If the pipe2 syscall is missing and
2260C<$flags> is non-zero, fails with C<ENOSYS>.
2261
2262Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
2263time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
2264C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported.
1603 2265
1604=back 2266=back
1605 2267
1606=cut 2268=cut
1607 2269
1642 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno => 2304 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
1643 \&IO::AIO::poll_cb); 2305 \&IO::AIO::poll_cb);
1644 2306
1645=head2 FORK BEHAVIOUR 2307=head2 FORK BEHAVIOUR
1646 2308
1647This module should do "the right thing" when the process using it forks: 2309Usage of pthreads in a program changes the semantics of fork
2310considerably. Specifically, only async-safe functions can be called after
2311fork. Perl doesn't know about this, so in general, you cannot call fork
2312with defined behaviour in perl if pthreads are involved. IO::AIO uses
2313pthreads, so this applies, but many other extensions and (for inexplicable
2314reasons) perl itself often is linked against pthreads, so this limitation
2315applies to quite a lot of perls.
1648 2316
1649Before the fork, IO::AIO enters a quiescent state where no requests 2317This module no longer tries to fight your OS, or POSIX. That means IO::AIO
1650can be added in other threads and no results will be processed. After 2318only works in the process that loaded it. Forking is fully supported, but
1651the fork the parent simply leaves the quiescent state and continues 2319using IO::AIO in the child is not.
1652request/result processing, while the child frees the request/result queue
1653(so that the requests started before the fork will only be handled in the
1654parent). Threads will be started on demand until the limit set in the
1655parent process has been reached again.
1656 2320
1657In short: the parent will, after a short pause, continue as if fork had 2321You might get around by not I<using> IO::AIO before (or after)
1658not been called, while the child will act as if IO::AIO has not been used 2322forking. You could also try to call the L<IO::AIO::reinit> function in the
1659yet. 2323child:
2324
2325=over 4
2326
2327=item IO::AIO::reinit
2328
2329Abandons all current requests and I/O threads and simply reinitialises all
2330data structures. This is not an operation supported by any standards, but
2331happens to work on GNU/Linux and some newer BSD systems.
2332
2333The only reasonable use for this function is to call it after forking, if
2334C<IO::AIO> was used in the parent. Calling it while IO::AIO is active in
2335the process will result in undefined behaviour. Calling it at any time
2336will also result in any undefined (by POSIX) behaviour.
2337
2338=back
1660 2339
1661=head2 MEMORY USAGE 2340=head2 MEMORY USAGE
1662 2341
1663Per-request usage: 2342Per-request usage:
1664 2343

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines