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.205 by root, Mon Jul 18 03:09:06 2011 UTC vs.
Revision 1.281 by root, Tue Feb 20 04:32:59 2018 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
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;
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 = '4.0'; 176 our $VERSION = 4.4;
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_realpath 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_fallocate 181 aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
179 aio_pathsync aio_readahead 182 aio_pathsync aio_readahead aio_fiemap aio_allocate
180 aio_rename aio_link aio_move aio_copy aio_group 183 aio_rename aio_rename2 aio_link aio_move aio_copy aio_group
181 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
182 aio_chmod aio_utime aio_truncate 185 aio_chmod aio_utime aio_truncate
183 aio_msync aio_mtouch aio_mlock aio_mlockall 186 aio_msync aio_mtouch aio_mlock aio_mlockall
184 aio_statvfs); 187 aio_statvfs
188 aio_slurp
189 aio_wd);
185 190
186 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 191 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
187 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 192 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
188 min_parallel max_parallel max_idle idle_timeout 193 min_parallel max_parallel max_idle idle_timeout
189 nreqs nready npending nthreads 194 nreqs nready npending nthreads
201 206
202=head1 FUNCTIONS 207=head1 FUNCTIONS
203 208
204=head2 QUICK OVERVIEW 209=head2 QUICK OVERVIEW
205 210
206This section simply lists the prototypes of the most important functions 211This section simply lists the prototypes most of the functions for
207for quick reference. See the following sections for function-by-function 212quick reference. See the following sections for function-by-function
208documentation. 213documentation.
209 214
215 aio_wd $pathname, $callback->($wd)
210 aio_open $pathname, $flags, $mode, $callback->($fh) 216 aio_open $pathname, $flags, $mode, $callback->($fh)
211 aio_close $fh, $callback->($status) 217 aio_close $fh, $callback->($status)
218 aio_seek $fh,$offset,$whence, $callback->($offs)
212 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 219 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
213 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 220 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
214 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval) 221 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
215 aio_readahead $fh,$offset,$length, $callback->($retval) 222 aio_readahead $fh,$offset,$length, $callback->($retval)
216 aio_stat $fh_or_path, $callback->($status) 223 aio_stat $fh_or_path, $callback->($status)
217 aio_lstat $fh, $callback->($status) 224 aio_lstat $fh, $callback->($status)
218 aio_statvfs $fh_or_path, $callback->($statvfs) 225 aio_statvfs $fh_or_path, $callback->($statvfs)
219 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 226 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
220 aio_chown $fh_or_path, $uid, $gid, $callback->($status) 227 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
228 aio_chmod $fh_or_path, $mode, $callback->($status)
221 aio_truncate $fh_or_path, $offset, $callback->($status) 229 aio_truncate $fh_or_path, $offset, $callback->($status)
222 aio_chmod $fh_or_path, $mode, $callback->($status) 230 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
231 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
223 aio_unlink $pathname, $callback->($status) 232 aio_unlink $pathname, $callback->($status)
224 aio_mknod $path, $mode, $dev, $callback->($status) 233 aio_mknod $pathname, $mode, $dev, $callback->($status)
225 aio_link $srcpath, $dstpath, $callback->($status) 234 aio_link $srcpath, $dstpath, $callback->($status)
226 aio_symlink $srcpath, $dstpath, $callback->($status) 235 aio_symlink $srcpath, $dstpath, $callback->($status)
227 aio_readlink $path, $callback->($link) 236 aio_readlink $pathname, $callback->($link)
228 aio_realpath $path, $callback->($link) 237 aio_realpath $pathname, $callback->($path)
229 aio_rename $srcpath, $dstpath, $callback->($status) 238 aio_rename $srcpath, $dstpath, $callback->($status)
239 aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
230 aio_mkdir $pathname, $mode, $callback->($status) 240 aio_mkdir $pathname, $mode, $callback->($status)
231 aio_rmdir $pathname, $callback->($status) 241 aio_rmdir $pathname, $callback->($status)
232 aio_readdir $pathname, $callback->($entries) 242 aio_readdir $pathname, $callback->($entries)
233 aio_readdirx $pathname, $flags, $callback->($entries, $flags) 243 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
234 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST 244 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
235 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN 245 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
246 aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
236 aio_load $path, $data, $callback->($status) 247 aio_load $pathname, $data, $callback->($status)
237 aio_copy $srcpath, $dstpath, $callback->($status) 248 aio_copy $srcpath, $dstpath, $callback->($status)
238 aio_move $srcpath, $dstpath, $callback->($status) 249 aio_move $srcpath, $dstpath, $callback->($status)
239 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
240 aio_rmtree $path, $callback->($status) 250 aio_rmtree $pathname, $callback->($status)
251 aio_fcntl $fh, $cmd, $arg, $callback->($status)
252 aio_ioctl $fh, $request, $buf, $callback->($status)
241 aio_sync $callback->($status) 253 aio_sync $callback->($status)
254 aio_syncfs $fh, $callback->($status)
242 aio_fsync $fh, $callback->($status) 255 aio_fsync $fh, $callback->($status)
243 aio_fdatasync $fh, $callback->($status) 256 aio_fdatasync $fh, $callback->($status)
244 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 257 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
245 aio_pathsync $path, $callback->($status) 258 aio_pathsync $pathname, $callback->($status)
246 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 259 aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
247 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 260 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
248 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) 261 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
249 aio_mlockall $flags, $callback->($status) 262 aio_mlockall $flags, $callback->($status)
250 aio_group $callback->(...) 263 aio_group $callback->(...)
251 aio_nop $callback->() 264 aio_nop $callback->()
265 IO::AIO::idle_timeout $seconds 278 IO::AIO::idle_timeout $seconds
266 IO::AIO::max_outstanding $maxreqs 279 IO::AIO::max_outstanding $maxreqs
267 IO::AIO::nreqs 280 IO::AIO::nreqs
268 IO::AIO::nready 281 IO::AIO::nready
269 IO::AIO::npending 282 IO::AIO::npending
283 $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]
284 IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]
270 285
271 IO::AIO::sendfile $ofh, $ifh, $offset, $count 286 IO::AIO::sendfile $ofh, $ifh, $offset, $count
272 IO::AIO::fadvise $fh, $offset, $len, $advice 287 IO::AIO::fadvise $fh, $offset, $len, $advice
288 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
289 IO::AIO::munmap $scalar
273 IO::AIO::madvise $scalar, $offset, $length, $advice 290 IO::AIO::madvise $scalar, $offset, $length, $advice
274 IO::AIO::mprotect $scalar, $offset, $length, $protect 291 IO::AIO::mprotect $scalar, $offset, $length, $protect
275 IO::AIO::munlock $scalar, $offset = 0, $length = undef 292 IO::AIO::munlock $scalar, $offset = 0, $length = undef
276 IO::AIO::munlockall 293 IO::AIO::munlockall
277 294
278=head2 AIO REQUEST FUNCTIONS 295=head2 API NOTES
279 296
280All the C<aio_*> calls are more or less thin wrappers around the syscall 297All the C<aio_*> calls are more or less thin wrappers around the syscall
281with the same name (sans C<aio_>). The arguments are similar or identical, 298with the same name (sans C<aio_>). The arguments are similar or identical,
282and they all accept an additional (and optional) C<$callback> argument 299and they all accept an additional (and optional) C<$callback> argument
283which must be a code reference. This code reference will get called with 300which must be a code reference. This code reference will be called after
284the syscall return code (e.g. most syscalls return C<-1> on error, unlike 301the syscall has been executed in an asynchronous fashion. The results
285perl, which usually delivers "false") as its sole argument after the given 302of the request will be passed as arguments to the callback (and, if an
286syscall has been executed asynchronously. 303error occured, in C<$!>) - for most requests the syscall return code (e.g.
304most syscalls return C<-1> on error, unlike perl, which usually delivers
305"false").
306
307Some requests (such as C<aio_readdir>) pass the actual results and
308communicate failures by passing C<undef>.
287 309
288All functions expecting a filehandle keep a copy of the filehandle 310All functions expecting a filehandle keep a copy of the filehandle
289internally until the request has finished. 311internally until the request has finished.
290 312
291All functions return request objects of type L<IO::AIO::REQ> that allow 313All functions return request objects of type L<IO::AIO::REQ> that allow
292further manipulation of those requests while they are in-flight. 314further manipulation of those requests while they are in-flight.
293 315
294The pathnames you pass to these routines I<must> be absolute and 316The pathnames you pass to these routines I<should> be absolute. The
295encoded as octets. The reason for the former is that at the time the 317reason for this is that at the time the request is being executed, the
296request is being executed, the current working directory could have 318current working directory could have changed. Alternatively, you can
297changed. Alternatively, you can make sure that you never change the 319make sure that you never change the current working directory anywhere
298current working directory anywhere in the program and then use relative 320in the program and then use relative paths. You can also take advantage
299paths. 321of IO::AIOs working directory abstraction, that lets you specify paths
322relative to some previously-opened "working directory object" - see the
323description of the C<IO::AIO::WD> class later in this document.
300 324
301To encode pathnames as octets, either make sure you either: a) always pass 325To encode pathnames as octets, either make sure you either: a) always pass
302in filenames you got from outside (command line, readdir etc.) without 326in filenames you got from outside (command line, readdir etc.) without
303tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode 327tinkering, b) are in your native filesystem encoding, c) use the Encode
304your pathnames to the locale (or other) encoding in effect in the user 328module and encode your pathnames to the locale (or other) encoding in
305environment, d) use Glib::filename_from_unicode on unicode filenames or e) 329effect in the user environment, d) use Glib::filename_from_unicode on
306use something else to ensure your scalar has the correct contents. 330unicode filenames or e) use something else to ensure your scalar has the
331correct contents.
307 332
308This works, btw. independent of the internal UTF-8 bit, which IO::AIO 333This works, btw. independent of the internal UTF-8 bit, which IO::AIO
309handles correctly whether it is set or not. 334handles correctly whether it is set or not.
335
336=head2 AIO REQUEST FUNCTIONS
310 337
311=over 4 338=over 4
312 339
313=item $prev_pri = aioreq_pri [$pri] 340=item $prev_pri = aioreq_pri [$pri]
314 341
344 371
345 372
346=item aio_open $pathname, $flags, $mode, $callback->($fh) 373=item aio_open $pathname, $flags, $mode, $callback->($fh)
347 374
348Asynchronously open or create a file and call the callback with a newly 375Asynchronously open or create a file and call the callback with a newly
349created filehandle for the file. 376created filehandle for the file (or C<undef> in case of an error).
350 377
351The pathname passed to C<aio_open> must be absolute. See API NOTES, above, 378The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
352for an explanation. 379for an explanation.
353 380
354The C<$flags> argument is a bitmask. See the C<Fcntl> module for a 381The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
377following POSIX and non-POSIX constants are available (missing ones on 404following POSIX and non-POSIX constants are available (missing ones on
378your system are, as usual, C<0>): 405your system are, as usual, C<0>):
379 406
380C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>, 407C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
381C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>, 408C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
382C<O_RSYNC>, C<O_SYNC> and C<O_TTY_INIT>. 409C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, and C<O_TTY_INIT>.
383 410
384 411
385=item aio_close $fh, $callback->($status) 412=item aio_close $fh, $callback->($status)
386 413
387Asynchronously close a file and call the callback with the result 414Asynchronously close a file and call the callback with the result
397Or in other words: the file descriptor will be closed, but it will not be 424Or in other words: the file descriptor will be closed, but it will not be
398free for reuse until the perl filehandle is closed. 425free for reuse until the perl filehandle is closed.
399 426
400=cut 427=cut
401 428
429=item aio_seek $fh, $offset, $whence, $callback->($offs)
430
431Seeks the filehandle to the new C<$offset>, similarly to perl's
432C<sysseek>. The C<$whence> can use the traditional values (C<0> for
433C<IO::AIO::SEEK_SET>, C<1> for C<IO::AIO::SEEK_CUR> or C<2> for
434C<IO::AIO::SEEK_END>).
435
436The resulting absolute offset will be passed to the callback, or C<-1> in
437case of an error.
438
439In theory, the C<$whence> constants could be different than the
440corresponding values from L<Fcntl>, but perl guarantees they are the same,
441so don't panic.
442
443As a GNU/Linux (and maybe Solaris) extension, also the constants
444C<IO::AIO::SEEK_DATA> and C<IO::AIO::SEEK_HOLE> are available, if they
445could be found. No guarantees about suitability for use in C<aio_seek> or
446Perl's C<sysseek> can be made though, although I would naively assume they
447"just work".
448
402=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 449=item aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
403 450
404=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval) 451=item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
405 452
406Reads or writes C<$length> bytes from or to the specified C<$fh> and 453Reads or writes C<$length> bytes from or to the specified C<$fh> and
407C<$offset> into the scalar given by C<$data> and offset C<$dataoffset> 454C<$offset> into the scalar given by C<$data> and offset C<$dataoffset> and
408and calls the callback without the actual number of bytes read (or -1 on 455calls the callback with the actual number of bytes transferred (or -1 on
409error, just like the syscall). 456error, just like the syscall).
410 457
411C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to 458C<aio_read> will, like C<sysread>, shrink or grow the C<$data> scalar to
412offset plus the actual number of bytes read. 459offset plus the actual number of bytes read.
413 460
471As native sendfile syscalls (as practically any non-POSIX interface hacked 518As native sendfile syscalls (as practically any non-POSIX interface hacked
472together in a hurry to improve benchmark numbers) tend to be rather buggy 519together in a hurry to improve benchmark numbers) tend to be rather buggy
473on many systems, this implementation tries to work around some known bugs 520on many systems, this implementation tries to work around some known bugs
474in Linux and FreeBSD kernels (probably others, too), but that might fail, 521in Linux and FreeBSD kernels (probably others, too), but that might fail,
475so you really really should check the return value of C<aio_sendfile> - 522so you really really should check the return value of C<aio_sendfile> -
476fewre bytes than expected might have been transferred. 523fewer bytes than expected might have been transferred.
477 524
478 525
479=item aio_readahead $fh,$offset,$length, $callback->($retval) 526=item aio_readahead $fh,$offset,$length, $callback->($retval)
480 527
481C<aio_readahead> populates the page cache with data from a file so that 528C<aio_readahead> populates the page cache with data from a file so that
485whole pages, so that offset is effectively rounded down to a page boundary 532whole pages, so that offset is effectively rounded down to a page boundary
486and bytes are read up to the next page boundary greater than or equal to 533and bytes are read up to the next page boundary greater than or equal to
487(off-set+length). C<aio_readahead> does not read beyond the end of the 534(off-set+length). C<aio_readahead> does not read beyond the end of the
488file. The current file offset of the file is left unchanged. 535file. The current file offset of the file is left unchanged.
489 536
490If that syscall doesn't exist (likely if your OS isn't Linux) it will be 537If that syscall doesn't exist (likely if your kernel isn't Linux) it will
491emulated by simply reading the data, which would have a similar effect. 538be emulated by simply reading the data, which would have a similar effect.
492 539
493 540
494=item aio_stat $fh_or_path, $callback->($status) 541=item aio_stat $fh_or_path, $callback->($status)
495 542
496=item aio_lstat $fh, $callback->($status) 543=item aio_lstat $fh, $callback->($status)
565 namemax => 255, 612 namemax => 255,
566 frsize => 1024, 613 frsize => 1024,
567 fsid => 1810 614 fsid => 1810
568 } 615 }
569 616
570
571=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 617=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
572 618
573Works like perl's C<utime> function (including the special case of $atime 619Works like perl's C<utime> function (including the special case of $atime
574and $mtime being undef). Fractional times are supported if the underlying 620and $mtime being undef). Fractional times are supported if the underlying
575syscalls support them. 621syscalls support them.
602=item aio_truncate $fh_or_path, $offset, $callback->($status) 648=item aio_truncate $fh_or_path, $offset, $callback->($status)
603 649
604Works like truncate(2) or ftruncate(2). 650Works like truncate(2) or ftruncate(2).
605 651
606 652
653=item aio_allocate $fh, $mode, $offset, $len, $callback->($status)
654
655Allocates or frees disk space according to the C<$mode> argument. See the
656linux C<fallocate> documentation for details.
657
658C<$mode> is usually C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> to allocate
659space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE>,
660to deallocate a file range.
661
662IO::AIO also supports C<FALLOC_FL_COLLAPSE_RANGE>, to remove a range
663(without leaving a hole), C<FALLOC_FL_ZERO_RANGE>, to zero a range,
664C<FALLOC_FL_INSERT_RANGE> to insert a range and C<FALLOC_FL_UNSHARE_RANGE>
665to unshare shared blocks (see your L<fallocate(2)> manpage).
666
667The file system block size used by C<fallocate> is presumably the
668C<f_bsize> returned by C<statvfs>, but different filesystems and filetypes
669can dictate other limitations.
670
671If C<fallocate> isn't available or cannot be emulated (currently no
672emulation will be attempted), passes C<-1> and sets C<$!> to C<ENOSYS>.
673
674
607=item aio_chmod $fh_or_path, $mode, $callback->($status) 675=item aio_chmod $fh_or_path, $mode, $callback->($status)
608 676
609Works like perl's C<chmod> function. 677Works like perl's C<chmod> function.
610 678
611 679
613 681
614Asynchronously unlink (delete) a file and call the callback with the 682Asynchronously unlink (delete) a file and call the callback with the
615result code. 683result code.
616 684
617 685
618=item aio_mknod $path, $mode, $dev, $callback->($status) 686=item aio_mknod $pathname, $mode, $dev, $callback->($status)
619 687
620[EXPERIMENTAL] 688[EXPERIMENTAL]
621 689
622Asynchronously create a device node (or fifo). See mknod(2). 690Asynchronously create a device node (or fifo). See mknod(2).
623 691
624The only (POSIX-) portable way of calling this function is: 692The only (POSIX-) portable way of calling this function is:
625 693
626 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 694 aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
627 695
628See C<aio_stat> for info about some potentially helpful extra constants 696See C<aio_stat> for info about some potentially helpful extra constants
629and functions. 697and functions.
630 698
631=item aio_link $srcpath, $dstpath, $callback->($status) 699=item aio_link $srcpath, $dstpath, $callback->($status)
638 706
639Asynchronously create a new symbolic link to the existing object at C<$srcpath> at 707Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
640the path C<$dstpath> and call the callback with the result code. 708the path C<$dstpath> and call the callback with the result code.
641 709
642 710
643=item aio_readlink $path, $callback->($link) 711=item aio_readlink $pathname, $callback->($link)
644 712
645Asynchronously read the symlink specified by C<$path> and pass it to 713Asynchronously read the symlink specified by C<$path> and pass it to
646the callback. If an error occurs, nothing or undef gets passed to the 714the callback. If an error occurs, nothing or undef gets passed to the
647callback. 715callback.
648 716
649 717
650=item aio_realpath $path, $callback->($path) 718=item aio_realpath $pathname, $callback->($path)
651 719
652Asynchronously make the path absolute and resolve any symlinks in 720Asynchronously make the path absolute and resolve any symlinks in
653C<$path>. The resulting path only consists of directories (Same as 721C<$path>. The resulting path only consists of directories (same as
654L<Cwd::realpath>). 722L<Cwd::realpath>).
655 723
656This request can be used to get the absolute path of the current working 724This request can be used to get the absolute path of the current working
657directory by passing it a path of F<.> (a single dot). 725directory by passing it a path of F<.> (a single dot).
658 726
659 727
660=item aio_rename $srcpath, $dstpath, $callback->($status) 728=item aio_rename $srcpath, $dstpath, $callback->($status)
661 729
662Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 730Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
663rename(2) and call the callback with the result code. 731rename(2) and call the callback with the result code.
732
733On systems that support the AIO::WD working directory abstraction
734natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
735of failing, C<rename> is called on the absolute path of C<$wd>.
736
737
738=item aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
739
740Basically a version of C<aio_rename> with an additional C<$flags>
741argument. Calling this with C<$flags=0> is the same as calling
742C<aio_rename>.
743
744Non-zero flags are currently only supported on GNU/Linux systems that
745support renameat2. Other systems fail with C<ENOSYS> in this case.
746
747The following constants are available (missing ones are, as usual C<0>),
748see renameat2(2) for details:
749
750C<IO::AIO::RENAME_NOREPLACE>, C<IO::AIO::RENAME_EXCHANGE>
751and C<IO::AIO::RENAME_WHITEOUT>.
664 752
665 753
666=item aio_mkdir $pathname, $mode, $callback->($status) 754=item aio_mkdir $pathname, $mode, $callback->($status)
667 755
668Asynchronously mkdir (create) a directory and call the callback with 756Asynchronously mkdir (create) a directory and call the callback with
673=item aio_rmdir $pathname, $callback->($status) 761=item aio_rmdir $pathname, $callback->($status)
674 762
675Asynchronously rmdir (delete) a directory and call the callback with the 763Asynchronously rmdir (delete) a directory and call the callback with the
676result code. 764result code.
677 765
766On systems that support the AIO::WD working directory abstraction
767natively, the case C<[$wd, "."]> is specialcased - instead of failing,
768C<rmdir> is called on the absolute path of C<$wd>.
769
678 770
679=item aio_readdir $pathname, $callback->($entries) 771=item aio_readdir $pathname, $callback->($entries)
680 772
681Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 773Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
682directory (i.e. opendir + readdir + closedir). The entries will not be 774directory (i.e. opendir + readdir + closedir). The entries will not be
686array-ref with the filenames. 778array-ref with the filenames.
687 779
688 780
689=item aio_readdirx $pathname, $flags, $callback->($entries, $flags) 781=item aio_readdirx $pathname, $flags, $callback->($entries, $flags)
690 782
691Quite similar to C<aio_readdir>, but the C<$flags> argument allows to tune 783Quite similar to C<aio_readdir>, but the C<$flags> argument allows one to
692behaviour and output format. In case of an error, C<$entries> will be 784tune behaviour and output format. In case of an error, C<$entries> will be
693C<undef>. 785C<undef>.
694 786
695The flags are a combination of the following constants, ORed together (the 787The flags are a combination of the following constants, ORed together (the
696flags will also be passed to the callback, possibly modified): 788flags will also be passed to the callback, possibly modified):
697 789
744 836
745=item IO::AIO::READDIR_FOUND_UNKNOWN 837=item IO::AIO::READDIR_FOUND_UNKNOWN
746 838
747This flag should not be set when calling C<aio_readdirx>. Instead, it 839This flag should not be set when calling C<aio_readdirx>. Instead, it
748is being set by C<aio_readdirx>, when any of the C<$type>'s found were 840is being set by C<aio_readdirx>, when any of the C<$type>'s found were
749C<IO::AIO::DT_UNKNOWN>. The absense of this flag therefore indicates that all 841C<IO::AIO::DT_UNKNOWN>. The absence of this flag therefore indicates that all
750C<$type>'s are known, which can be used to speed up some algorithms. 842C<$type>'s are known, which can be used to speed up some algorithms.
751 843
752=back 844=back
753 845
754 846
847=item aio_slurp $pathname, $offset, $length, $data, $callback->($status)
848
849Opens, reads and closes the given file. The data is put into C<$data>,
850which is resized as required.
851
852If C<$offset> is negative, then it is counted from the end of the file.
853
854If C<$length> is zero, then the remaining length of the file is
855used. Also, in this case, the same limitations to modifying C<$data> apply
856as when IO::AIO::mmap is used, i.e. it must only be modified in-place
857with C<substr>. If the size of the file is known, specifying a non-zero
858C<$length> results in a performance advantage.
859
860This request is similar to the older C<aio_load> request, but since it is
861a single request, it might be more efficient to use.
862
863Example: load F</etc/passwd> into C<$passwd>.
864
865 my $passwd;
866 aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
867 $_[0] >= 0
868 or die "/etc/passwd: $!\n";
869
870 printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
871 print $passwd;
872 };
873 IO::AIO::flush;
874
875
755=item aio_load $path, $data, $callback->($status) 876=item aio_load $pathname, $data, $callback->($status)
756 877
757This is a composite request that tries to fully load the given file into 878This is a composite request that tries to fully load the given file into
758memory. Status is the same as with aio_read. 879memory. Status is the same as with aio_read.
880
881Using C<aio_slurp> might be more efficient, as it is a single request.
759 882
760=cut 883=cut
761 884
762sub aio_load($$;$) { 885sub aio_load($$;$) {
763 my ($path, undef, $cb) = @_; 886 my ($path, undef, $cb) = @_;
783=item aio_copy $srcpath, $dstpath, $callback->($status) 906=item aio_copy $srcpath, $dstpath, $callback->($status)
784 907
785Try to copy the I<file> (directories not supported as either source or 908Try to copy the I<file> (directories not supported as either source or
786destination) from C<$srcpath> to C<$dstpath> and call the callback with 909destination) from C<$srcpath> to C<$dstpath> and call the callback with
787a status of C<0> (ok) or C<-1> (error, see C<$!>). 910a status of C<0> (ok) or C<-1> (error, see C<$!>).
911
912Existing destination files will be truncated.
788 913
789This is a composite request that creates the destination file with 914This is a composite request that creates the destination file with
790mode 0200 and copies the contents of the source file into it using 915mode 0200 and copies the contents of the source file into it using
791C<aio_sendfile>, followed by restoring atime, mtime, access mode and 916C<aio_sendfile>, followed by restoring atime, mtime, access mode and
792uid/gid, in that order. 917uid/gid, in that order.
895 }; 1020 };
896 1021
897 $grp 1022 $grp
898} 1023}
899 1024
900=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 1025=item aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
901 1026
902Scans a directory (similar to C<aio_readdir>) but additionally tries to 1027Scans a directory (similar to C<aio_readdir>) but additionally tries to
903efficiently separate the entries of directory C<$path> into two sets of 1028efficiently separate the entries of directory C<$path> into two sets of
904names, directories you can recurse into (directories), and ones you cannot 1029names, directories you can recurse into (directories), and ones you cannot
905recurse into (everything else, including symlinks to directories). 1030recurse into (everything else, including symlinks to directories).
906 1031
907C<aio_scandir> is a composite request that creates of many sub requests_ 1032C<aio_scandir> is a composite request that generates many sub requests.
908C<$maxreq> specifies the maximum number of outstanding aio requests that 1033C<$maxreq> specifies the maximum number of outstanding aio requests that
909this function generates. If it is C<< <= 0 >>, then a suitable default 1034this function generates. If it is C<< <= 0 >>, then a suitable default
910will be chosen (currently 4). 1035will be chosen (currently 4).
911 1036
912On error, the callback is called without arguments, otherwise it receives 1037On error, the callback is called without arguments, otherwise it receives
936Then entries will be sorted into likely directories a non-initial dot 1061Then entries will be sorted into likely directories a non-initial dot
937currently) and likely non-directories (see C<aio_readdirx>). Then every 1062currently) and likely non-directories (see C<aio_readdirx>). Then every
938entry plus an appended C</.> will be C<stat>'ed, likely directories first, 1063entry plus an appended C</.> will be C<stat>'ed, likely directories first,
939in order of their inode numbers. If that succeeds, it assumes that the 1064in order of their inode numbers. If that succeeds, it assumes that the
940entry is a directory or a symlink to directory (which will be checked 1065entry is a directory or a symlink to directory (which will be checked
941seperately). This is often faster than stat'ing the entry itself because 1066separately). This is often faster than stat'ing the entry itself because
942filesystems might detect the type of the entry without reading the inode 1067filesystems might detect the type of the entry without reading the inode
943data (e.g. ext2fs filetype feature), even on systems that cannot return 1068data (e.g. ext2fs filetype feature), even on systems that cannot return
944the filetype information on readdir. 1069the filetype information on readdir.
945 1070
946If the known number of directories (link count - 2) has been reached, the 1071If the known number of directories (link count - 2) has been reached, the
962 1087
963 my $grp = aio_group $cb; 1088 my $grp = aio_group $cb;
964 1089
965 $maxreq = 4 if $maxreq <= 0; 1090 $maxreq = 4 if $maxreq <= 0;
966 1091
967 # stat once 1092 # get a wd object
968 aioreq_pri $pri; 1093 aioreq_pri $pri;
969 add $grp aio_stat $path, sub { 1094 add $grp aio_wd $path, sub {
1095 $_[0]
970 return $grp->result () if $_[0]; 1096 or return $grp->result ();
971 my $now = time;
972 my $hash1 = join ":", (stat _)[0,1,3,7,9];
973 1097
974 # read the directory entries 1098 my $wd = [shift, "."];
1099
1100 # stat once
975 aioreq_pri $pri; 1101 aioreq_pri $pri;
976 add $grp aio_readdirx $path, READDIR_DIRS_FIRST, sub { 1102 add $grp aio_stat $wd, sub {
977 my $entries = shift
978 or return $grp->result (); 1103 return $grp->result () if $_[0];
1104 my $now = time;
1105 my $hash1 = join ":", (stat _)[0,1,3,7,9];
979 1106
980 # stat the dir another time 1107 # read the directory entries
981 aioreq_pri $pri; 1108 aioreq_pri $pri;
1109 add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {
1110 my $entries = shift
1111 or return $grp->result ();
1112
1113 # stat the dir another time
1114 aioreq_pri $pri;
982 add $grp aio_stat $path, sub { 1115 add $grp aio_stat $wd, sub {
983 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 1116 my $hash2 = join ":", (stat _)[0,1,3,7,9];
984 1117
985 my $ndirs; 1118 my $ndirs;
986 1119
987 # take the slow route if anything looks fishy 1120 # take the slow route if anything looks fishy
988 if ($hash1 ne $hash2 or (stat _)[9] == $now) { 1121 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
989 $ndirs = -1; 1122 $ndirs = -1;
990 } else { 1123 } else {
991 # if nlink == 2, we are finished 1124 # if nlink == 2, we are finished
992 # for non-posix-fs's, we rely on nlink < 2 1125 # for non-posix-fs's, we rely on nlink < 2
993 $ndirs = (stat _)[3] - 2 1126 $ndirs = (stat _)[3] - 2
994 or return $grp->result ([], $entries); 1127 or return $grp->result ([], $entries);
995 } 1128 }
996 1129
997 my (@dirs, @nondirs); 1130 my (@dirs, @nondirs);
998 1131
999 my $statgrp = add $grp aio_group sub { 1132 my $statgrp = add $grp aio_group sub {
1000 $grp->result (\@dirs, \@nondirs); 1133 $grp->result (\@dirs, \@nondirs);
1001 }; 1134 };
1002 1135
1003 limit $statgrp $maxreq; 1136 limit $statgrp $maxreq;
1004 feed $statgrp sub { 1137 feed $statgrp sub {
1005 return unless @$entries; 1138 return unless @$entries;
1006 my $entry = shift @$entries; 1139 my $entry = shift @$entries;
1007 1140
1008 aioreq_pri $pri; 1141 aioreq_pri $pri;
1142 $wd->[1] = "$entry/.";
1009 add $statgrp aio_stat "$path/$entry/.", sub { 1143 add $statgrp aio_stat $wd, sub {
1010 if ($_[0] < 0) { 1144 if ($_[0] < 0) {
1011 push @nondirs, $entry; 1145 push @nondirs, $entry;
1012 } else { 1146 } else {
1013 # need to check for real directory 1147 # need to check for real directory
1014 aioreq_pri $pri; 1148 aioreq_pri $pri;
1149 $wd->[1] = $entry;
1015 add $statgrp aio_lstat "$path/$entry", sub { 1150 add $statgrp aio_lstat $wd, sub {
1016 if (-d _) { 1151 if (-d _) {
1017 push @dirs, $entry; 1152 push @dirs, $entry;
1018 1153
1019 unless (--$ndirs) { 1154 unless (--$ndirs) {
1020 push @nondirs, @$entries; 1155 push @nondirs, @$entries;
1021 feed $statgrp; 1156 feed $statgrp;
1157 }
1158 } else {
1159 push @nondirs, $entry;
1022 } 1160 }
1023 } else {
1024 push @nondirs, $entry;
1025 } 1161 }
1026 } 1162 }
1027 } 1163 };
1028 }; 1164 };
1029 }; 1165 };
1030 }; 1166 };
1031 }; 1167 };
1032 }; 1168 };
1033 1169
1034 $grp 1170 $grp
1035} 1171}
1036 1172
1037=item aio_rmtree $path, $callback->($status) 1173=item aio_rmtree $pathname, $callback->($status)
1038 1174
1039Delete a directory tree starting (and including) C<$path>, return the 1175Delete a directory tree starting (and including) C<$path>, return the
1040status of the final C<rmdir> only. This is a composite request that 1176status of the final C<rmdir> only. This is a composite request that
1041uses C<aio_scandir> to recurse into and rmdir directories, and unlink 1177uses C<aio_scandir> to recurse into and rmdir directories, and unlink
1042everything else. 1178everything else.
1043 1179
1044=cut 1180=cut
1045 1181
1067 }; 1203 };
1068 1204
1069 $grp 1205 $grp
1070} 1206}
1071 1207
1208=item aio_fcntl $fh, $cmd, $arg, $callback->($status)
1209
1210=item aio_ioctl $fh, $request, $buf, $callback->($status)
1211
1212These work just like the C<fcntl> and C<ioctl> built-in functions, except
1213they execute asynchronously and pass the return value to the callback.
1214
1215Both calls can be used for a lot of things, some of which make more sense
1216to run asynchronously in their own thread, while some others make less
1217sense. For example, calls that block waiting for external events, such
1218as locking, will also lock down an I/O thread while it is waiting, which
1219can deadlock the whole I/O system. At the same time, there might be no
1220alternative to using a thread to wait.
1221
1222So in general, you should only use these calls for things that do
1223(filesystem) I/O, not for things that wait for other events (network,
1224other processes), although if you are careful and know what you are doing,
1225you still can.
1226
1227The following constants are available (missing ones are, as usual C<0>):
1228
1229C<F_DUPFD_CLOEXEC>,
1230
1231C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
1232
1233C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
1234
1235C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1236C<FS_IOC_FIEMAP>.
1237
1238C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
1239C<FS_IOC_GET_ENCRYPTION_PWSALT>, C<FS_IOC_GET_ENCRYPTION_POLICY>, C<FS_KEY_DESCRIPTOR_SIZE>.
1240
1241C<FS_SECRM_FL>, C<FS_UNRM_FL>, C<FS_COMPR_FL>, C<FS_SYNC_FL>, C<FS_IMMUTABLE_FL>,
1242C<FS_APPEND_FL>, C<FS_NODUMP_FL>, C<FS_NOATIME_FL>, C<FS_DIRTY_FL>,
1243C<FS_COMPRBLK_FL>, C<FS_NOCOMP_FL>, C<FS_ENCRYPT_FL>, C<FS_BTREE_FL>,
1244C<FS_INDEX_FL>, C<FS_JOURNAL_DATA_FL>, C<FS_NOTAIL_FL>, C<FS_DIRSYNC_FL>, C<FS_TOPDIR_FL>,
1245C<FS_FL_USER_MODIFIABLE>.
1246
1247C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1248C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1249C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1250C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
1251
1072=item aio_sync $callback->($status) 1252=item aio_sync $callback->($status)
1073 1253
1074Asynchronously call sync and call the callback when finished. 1254Asynchronously call sync and call the callback when finished.
1075 1255
1076=item aio_fsync $fh, $callback->($status) 1256=item aio_fsync $fh, $callback->($status)
1083Asynchronously call fdatasync on the given filehandle and call the 1263Asynchronously call fdatasync on the given filehandle and call the
1084callback with the fdatasync result code. 1264callback with the fdatasync result code.
1085 1265
1086If this call isn't available because your OS lacks it or it couldn't be 1266If this call isn't available because your OS lacks it or it couldn't be
1087detected, it will be emulated by calling C<fsync> instead. 1267detected, it will be emulated by calling C<fsync> instead.
1268
1269=item aio_syncfs $fh, $callback->($status)
1270
1271Asynchronously call the syncfs syscall to sync the filesystem associated
1272to the given filehandle and call the callback with the syncfs result
1273code. If syncfs is not available, calls sync(), but returns C<-1> and sets
1274errno to C<ENOSYS> nevertheless.
1088 1275
1089=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status) 1276=item aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
1090 1277
1091Sync the data portion of the file specified by C<$offset> and C<$length> 1278Sync the data portion of the file specified by C<$offset> and C<$length>
1092to disk (but NOT the metadata), by calling the Linux-specific 1279to disk (but NOT the metadata), by calling the Linux-specific
1096C<$flags> can be a combination of C<IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE>, 1283C<$flags> can be a combination of C<IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE>,
1097C<IO::AIO::SYNC_FILE_RANGE_WRITE> and 1284C<IO::AIO::SYNC_FILE_RANGE_WRITE> and
1098C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range 1285C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range
1099manpage for details. 1286manpage for details.
1100 1287
1101=item aio_pathsync $path, $callback->($status) 1288=item aio_pathsync $pathname, $callback->($status)
1102 1289
1103This request tries to open, fsync and close the given path. This is a 1290This request tries to open, fsync and close the given path. This is a
1104composite request intended to sync directories after directory operations 1291composite request intended to sync directories after directory operations
1105(E.g. rename). This might not work on all operating systems or have any 1292(E.g. rename). This might not work on all operating systems or have any
1106specific effect, but usually it makes sure that directory changes get 1293specific effect, but usually it makes sure that directory changes get
1137 }; 1324 };
1138 1325
1139 $grp 1326 $grp
1140} 1327}
1141 1328
1142=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1329=item aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
1143 1330
1144This is a rather advanced IO::AIO call, which only works on mmap(2)ed 1331This is a rather advanced IO::AIO call, which only works on mmap(2)ed
1145scalars (see the C<IO::AIO::mmap> function, although it also works on data 1332scalars (see the C<IO::AIO::mmap> function, although it also works on data
1146scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the 1333scalars managed by the L<Sys::Mmap> or L<Mmap> modules, note that the
1147scalar must only be modified in-place while an aio operation is pending on 1334scalar must only be modified in-place while an aio operation is pending on
1149 1336
1150It calls the C<msync> function of your OS, if available, with the memory 1337It calls the C<msync> function of your OS, if available, with the memory
1151area starting at C<$offset> in the string and ending C<$length> bytes 1338area starting at C<$offset> in the string and ending C<$length> bytes
1152later. If C<$length> is negative, counts from the end, and if C<$length> 1339later. If C<$length> is negative, counts from the end, and if C<$length>
1153is C<undef>, then it goes till the end of the string. The flags can be 1340is C<undef>, then it goes till the end of the string. The flags can be
1154a combination of C<IO::AIO::MS_ASYNC>, C<IO::AIO::MS_INVALIDATE> and 1341either C<IO::AIO::MS_ASYNC> or C<IO::AIO::MS_SYNC>, plus an optional
1155C<IO::AIO::MS_SYNC>. 1342C<IO::AIO::MS_INVALIDATE>.
1156 1343
1157=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) 1344=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
1158 1345
1159This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1346This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1160scalars. 1347scalars.
1161 1348
1162It touches (reads or writes) all memory pages in the specified 1349It touches (reads or writes) all memory pages in the specified
1163range inside the scalar. All caveats and parameters are the same 1350range inside the scalar. All caveats and parameters are the same
1164as for C<aio_msync>, above, except for flags, which must be either 1351as for C<aio_msync>, above, except for flags, which must be either
1165C<0> (which reads all pages and ensures they are instantiated) or 1352C<0> (which reads all pages and ensures they are instantiated) or
1166C<IO::AIO::MT_MODIFY>, which modifies the memory page s(by reading and 1353C<IO::AIO::MT_MODIFY>, which modifies the memory pages (by reading and
1167writing an octet from it, which dirties the page). 1354writing an octet from it, which dirties the page).
1168 1355
1169=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) 1356=item aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1170 1357
1171This is a rather advanced IO::AIO call, which works best on mmap(2)ed 1358This is a rather advanced IO::AIO call, which works best on mmap(2)ed
1202documented under L<MISCELLANEOUS FUNCTIONS>. 1389documented under L<MISCELLANEOUS FUNCTIONS>.
1203 1390
1204Example: asynchronously lock all current and future pages into memory. 1391Example: asynchronously lock all current and future pages into memory.
1205 1392
1206 aio_mlockall IO::AIO::MCL_FUTURE; 1393 aio_mlockall IO::AIO::MCL_FUTURE;
1394
1395=item aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1396
1397Queries the extents of the given file (by calling the Linux C<FIEMAP>
1398ioctl, see L<http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for details). If
1399the ioctl is not available on your OS, then this request will fail with
1400C<ENOSYS>.
1401
1402C<$start> is the starting offset to query extents for, C<$length> is the
1403size of the range to query - if it is C<undef>, then the whole file will
1404be queried.
1405
1406C<$flags> is a combination of flags (C<IO::AIO::FIEMAP_FLAG_SYNC> or
1407C<IO::AIO::FIEMAP_FLAG_XATTR> - C<IO::AIO::FIEMAP_FLAGS_COMPAT> is also
1408exported), and is normally C<0> or C<IO::AIO::FIEMAP_FLAG_SYNC> to query
1409the data portion.
1410
1411C<$count> is the maximum number of extent records to return. If it is
1412C<undef>, then IO::AIO queries all extents of the range. As a very special
1413case, if it is C<0>, then the callback receives the number of extents
1414instead of the extents themselves (which is unreliable, see below).
1415
1416If an error occurs, the callback receives no arguments. The special
1417C<errno> value C<IO::AIO::EBADR> is available to test for flag errors.
1418
1419Otherwise, the callback receives an array reference with extent
1420structures. Each extent structure is an array reference itself, with the
1421following members:
1422
1423 [$logical, $physical, $length, $flags]
1424
1425Flags is any combination of the following flag values (typically either C<0>
1426or C<IO::AIO::FIEMAP_EXTENT_LAST> (1)):
1427
1428C<IO::AIO::FIEMAP_EXTENT_LAST>, C<IO::AIO::FIEMAP_EXTENT_UNKNOWN>,
1429C<IO::AIO::FIEMAP_EXTENT_DELALLOC>, C<IO::AIO::FIEMAP_EXTENT_ENCODED>,
1430C<IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED>, C<IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED>,
1431C<IO::AIO::FIEMAP_EXTENT_DATA_INLINE>, C<IO::AIO::FIEMAP_EXTENT_DATA_TAIL>,
1432C<IO::AIO::FIEMAP_EXTENT_UNWRITTEN>, C<IO::AIO::FIEMAP_EXTENT_MERGED> or
1433C<IO::AIO::FIEMAP_EXTENT_SHARED>.
1434
1435At the time of this writing (Linux 3.2), this request is unreliable unless
1436C<$count> is C<undef>, as the kernel has all sorts of bugs preventing
1437it to return all extents of a range for files with a large number of
1438extents. The code (only) works around all these issues if C<$count> is
1439C<undef>.
1207 1440
1208=item aio_group $callback->(...) 1441=item aio_group $callback->(...)
1209 1442
1210This is a very special aio request: Instead of doing something, it is a 1443This is a very special aio request: Instead of doing something, it is a
1211container for other aio requests, which is useful if you want to bundle 1444container for other aio requests, which is useful if you want to bundle
1248like sleep and file handle readable/writable, the overhead this creates is 1481like sleep and file handle readable/writable, the overhead this creates is
1249immense (it blocks a thread for a long time) so do not use this function 1482immense (it blocks a thread for a long time) so do not use this function
1250except to put your application under artificial I/O pressure. 1483except to put your application under artificial I/O pressure.
1251 1484
1252=back 1485=back
1486
1487
1488=head2 IO::AIO::WD - multiple working directories
1489
1490Your process only has one current working directory, which is used by all
1491threads. This makes it hard to use relative paths (some other component
1492could call C<chdir> at any time, and it is hard to control when the path
1493will be used by IO::AIO).
1494
1495One solution for this is to always use absolute paths. This usually works,
1496but can be quite slow (the kernel has to walk the whole path on every
1497access), and can also be a hassle to implement.
1498
1499Newer POSIX systems have a number of functions (openat, fdopendir,
1500futimensat and so on) that make it possible to specify working directories
1501per operation.
1502
1503For portability, and because the clowns who "designed", or shall I write,
1504perpetrated this new interface were obviously half-drunk, this abstraction
1505cannot be perfect, though.
1506
1507IO::AIO allows you to convert directory paths into a so-called IO::AIO::WD
1508object. This object stores the canonicalised, absolute version of the
1509path, and on systems that allow it, also a directory file descriptor.
1510
1511Everywhere where a pathname is accepted by IO::AIO (e.g. in C<aio_stat>
1512or C<aio_unlink>), one can specify an array reference with an IO::AIO::WD
1513object and a pathname instead (or the IO::AIO::WD object alone, which
1514gets interpreted as C<[$wd, "."]>). If the pathname is absolute, the
1515IO::AIO::WD object is ignored, otherwise the pathname is resolved relative
1516to that IO::AIO::WD object.
1517
1518For example, to get a wd object for F</etc> and then stat F<passwd>
1519inside, you would write:
1520
1521 aio_wd "/etc", sub {
1522 my $etcdir = shift;
1523
1524 # although $etcdir can be undef on error, there is generally no reason
1525 # to check for errors here, as aio_stat will fail with ENOENT
1526 # when $etcdir is undef.
1527
1528 aio_stat [$etcdir, "passwd"], sub {
1529 # yay
1530 };
1531 };
1532
1533The fact that C<aio_wd> is a request and not a normal function shows that
1534creating an IO::AIO::WD object is itself a potentially blocking operation,
1535which is why it is done asynchronously.
1536
1537To stat the directory obtained with C<aio_wd> above, one could write
1538either of the following three request calls:
1539
1540 aio_lstat "/etc" , sub { ... # pathname as normal string
1541 aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
1542 aio_lstat $wd , sub { ... # shorthand for the previous
1543
1544As with normal pathnames, IO::AIO keeps a copy of the working directory
1545object and the pathname string, so you could write the following without
1546causing any issues due to C<$path> getting reused:
1547
1548 my $path = [$wd, undef];
1549
1550 for my $name (qw(abc def ghi)) {
1551 $path->[1] = $name;
1552 aio_stat $path, sub {
1553 # ...
1554 };
1555 }
1556
1557There are some caveats: when directories get renamed (or deleted), the
1558pathname string doesn't change, so will point to the new directory (or
1559nowhere at all), while the directory fd, if available on the system,
1560will still point to the original directory. Most functions accepting a
1561pathname will use the directory fd on newer systems, and the string on
1562older systems. Some functions (such as C<aio_realpath>) will always rely on
1563the string form of the pathname.
1564
1565So this functionality is mainly useful to get some protection against
1566C<chdir>, to easily get an absolute path out of a relative path for future
1567reference, and to speed up doing many operations in the same directory
1568(e.g. when stat'ing all files in a directory).
1569
1570The following functions implement this working directory abstraction:
1571
1572=over 4
1573
1574=item aio_wd $pathname, $callback->($wd)
1575
1576Asynchonously canonicalise the given pathname and convert it to an
1577IO::AIO::WD object representing it. If possible and supported on the
1578system, also open a directory fd to speed up pathname resolution relative
1579to this working directory.
1580
1581If something goes wrong, then C<undef> is passwd to the callback instead
1582of a working directory object and C<$!> is set appropriately. Since
1583passing C<undef> as working directory component of a pathname fails the
1584request with C<ENOENT>, there is often no need for error checking in the
1585C<aio_wd> callback, as future requests using the value will fail in the
1586expected way.
1587
1588=item IO::AIO::CWD
1589
1590This is a compiletime constant (object) that represents the process
1591current working directory.
1592
1593Specifying this object as working directory object for a pathname is as if
1594the pathname would be specified directly, without a directory object. For
1595example, these calls are functionally identical:
1596
1597 aio_stat "somefile", sub { ... };
1598 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1599
1600=back
1601
1602To recover the path associated with an IO::AIO::WD object, you can use
1603C<aio_realpath>:
1604
1605 aio_realpath $wd, sub {
1606 warn "path is $_[0]\n";
1607 };
1608
1609Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
1610sometimes, fall back to using an absolue path.
1253 1611
1254=head2 IO::AIO::REQ CLASS 1612=head2 IO::AIO::REQ CLASS
1255 1613
1256All non-aggregate C<aio_*> functions return an object of this class when 1614All non-aggregate C<aio_*> functions return an object of this class when
1257called in non-void context. 1615called in non-void context.
1375 1733
1376Sets a feeder/generator on this group: every group can have an attached 1734Sets a feeder/generator on this group: every group can have an attached
1377generator that generates requests if idle. The idea behind this is that, 1735generator that generates requests if idle. The idea behind this is that,
1378although you could just queue as many requests as you want in a group, 1736although you could just queue as many requests as you want in a group,
1379this might starve other requests for a potentially long time. For example, 1737this might starve other requests for a potentially long time. For example,
1380C<aio_scandir> might generate hundreds of thousands C<aio_stat> requests, 1738C<aio_scandir> might generate hundreds of thousands of C<aio_stat>
1381delaying any later requests for a long time. 1739requests, delaying any later requests for a long time.
1382 1740
1383To avoid this, and allow incremental generation of requests, you can 1741To avoid this, and allow incremental generation of requests, you can
1384instead a group and set a feeder on it that generates those requests. The 1742instead a group and set a feeder on it that generates those requests. The
1385feed callback will be called whenever there are few enough (see C<limit>, 1743feed callback will be called whenever there are few enough (see C<limit>,
1386below) requests active in the group itself and is expected to queue more 1744below) requests active in the group itself and is expected to queue more
1435 1793
1436See C<poll_cb> for an example. 1794See C<poll_cb> for an example.
1437 1795
1438=item IO::AIO::poll_cb 1796=item IO::AIO::poll_cb
1439 1797
1440Process some outstanding events on the result pipe. You have to call 1798Process some requests that have reached the result phase (i.e. they have
1799been executed but the results are not yet reported). You have to call
1800this "regularly" to finish outstanding requests.
1801
1441this regularly. Returns C<0> if all events could be processed (or there 1802Returns C<0> if all events could be processed (or there were no
1442were no events to process), or C<-1> if it returned earlier for whatever 1803events to process), or C<-1> if it returned earlier for whatever
1443reason. Returns immediately when no events are outstanding. The amount of 1804reason. Returns immediately when no events are outstanding. The amount
1444events processed depends on the settings of C<IO::AIO::max_poll_req> and 1805of events processed depends on the settings of C<IO::AIO::max_poll_req>,
1445C<IO::AIO::max_poll_time>. 1806C<IO::AIO::max_poll_time> and C<IO::AIO::max_outstanding>.
1446 1807
1447If not all requests were processed for whatever reason, the filehandle 1808If not all requests were processed for whatever reason, the poll file
1448will still be ready when C<poll_cb> returns, so normally you don't have to 1809descriptor will still be ready when C<poll_cb> returns, so normally you
1449do anything special to have it called later. 1810don't have to do anything special to have it called later.
1450 1811
1451Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes 1812Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
1452ready, it can be beneficial to call this function from loops which submit 1813ready, it can be beneficial to call this function from loops which submit
1453a lot of requests, to make sure the results get processed when they become 1814a lot of requests, to make sure the results get processed when they become
1454available and not just when the loop is finished and the event loop takes 1815available and not just when the loop is finished and the event loop takes
1463 poll => 'r', async => 1, 1824 poll => 'r', async => 1,
1464 cb => \&IO::AIO::poll_cb); 1825 cb => \&IO::AIO::poll_cb);
1465 1826
1466=item IO::AIO::poll_wait 1827=item IO::AIO::poll_wait
1467 1828
1468If there are any outstanding requests and none of them in the result 1829Wait until either at least one request is in the result phase or no
1469phase, wait till the result filehandle becomes ready for reading (simply 1830requests are outstanding anymore.
1470does a C<select> on the filehandle. This is useful if you want to 1831
1471synchronously wait for some requests to finish). 1832This is useful if you want to synchronously wait for some requests to
1833become ready, without actually handling them.
1472 1834
1473See C<nreqs> for an example. 1835See C<nreqs> for an example.
1474 1836
1475=item IO::AIO::poll 1837=item IO::AIO::poll
1476 1838
1597 1959
1598This is a very bad function to use in interactive programs because it 1960This is a very bad function to use in interactive programs because it
1599blocks, and a bad way to reduce concurrency because it is inexact: Better 1961blocks, and a bad way to reduce concurrency because it is inexact: Better
1600use an C<aio_group> together with a feed callback. 1962use an C<aio_group> together with a feed callback.
1601 1963
1602It's main use is in scripts without an event loop - when you want to stat 1964Its main use is in scripts without an event loop - when you want to stat
1603a lot of files, you can write somehting like this: 1965a lot of files, you can write something like this:
1604 1966
1605 IO::AIO::max_outstanding 32; 1967 IO::AIO::max_outstanding 32;
1606 1968
1607 for my $path (...) { 1969 for my $path (...) {
1608 aio_stat $path , ...; 1970 aio_stat $path , ...;
1647 2009
1648=back 2010=back
1649 2011
1650=head3 MISCELLANEOUS FUNCTIONS 2012=head3 MISCELLANEOUS FUNCTIONS
1651 2013
1652IO::AIO implements some functions that might be useful, but are not 2014IO::AIO implements some functions that are useful when you want to use
1653asynchronous. 2015some "Advanced I/O" function not available to in Perl, without going the
2016"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
2017counterpart.
1654 2018
1655=over 4 2019=over 4
2020
2021=item $numfd = IO::AIO::get_fdlimit
2022
2023This function is I<EXPERIMENTAL> and subject to change.
2024
2025Tries to find the current file descriptor limit and returns it, or
2026C<undef> and sets C<$!> in case of an error. The limit is one larger than
2027the highest valid file descriptor number.
2028
2029=item IO::AIO::min_fdlimit [$numfd]
2030
2031This function is I<EXPERIMENTAL> and subject to change.
2032
2033Try to increase the current file descriptor limit(s) to at least C<$numfd>
2034by changing the soft or hard file descriptor resource limit. If C<$numfd>
2035is missing, it will try to set a very high limit, although this is not
2036recommended when you know the actual minimum that you require.
2037
2038If the limit cannot be raised enough, the function makes a best-effort
2039attempt to increase the limit as much as possible, using various
2040tricks, while still failing. You can query the resulting limit using
2041C<IO::AIO::get_fdlimit>.
2042
2043If an error occurs, returns C<undef> and sets C<$!>, otherwise returns
2044true.
1656 2045
1657=item IO::AIO::sendfile $ofh, $ifh, $offset, $count 2046=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1658 2047
1659Calls the C<eio_sendfile_sync> function, which is like C<aio_sendfile>, 2048Calls the C<eio_sendfile_sync> function, which is like C<aio_sendfile>,
1660but is blocking (this makes most sense if you know the input data is 2049but is blocking (this makes most sense if you know the input data is
1665 2054
1666=item IO::AIO::fadvise $fh, $offset, $len, $advice 2055=item IO::AIO::fadvise $fh, $offset, $len, $advice
1667 2056
1668Simply calls the C<posix_fadvise> function (see its 2057Simply calls the C<posix_fadvise> function (see its
1669manpage for details). The following advice constants are 2058manpage for details). The following advice constants are
1670avaiable: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>, 2059available: C<IO::AIO::FADV_NORMAL>, C<IO::AIO::FADV_SEQUENTIAL>,
1671C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>, 2060C<IO::AIO::FADV_RANDOM>, C<IO::AIO::FADV_NOREUSE>,
1672C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>. 2061C<IO::AIO::FADV_WILLNEED>, C<IO::AIO::FADV_DONTNEED>.
1673 2062
1674On systems that do not implement C<posix_fadvise>, this function returns 2063On systems that do not implement C<posix_fadvise>, this function returns
1675ENOSYS, otherwise the return value of C<posix_fadvise>. 2064ENOSYS, otherwise the return value of C<posix_fadvise>.
1676 2065
1677=item IO::AIO::madvise $scalar, $offset, $len, $advice 2066=item IO::AIO::madvise $scalar, $offset, $len, $advice
1678 2067
1679Simply calls the C<posix_madvise> function (see its 2068Simply calls the C<posix_madvise> function (see its
1680manpage for details). The following advice constants are 2069manpage for details). The following advice constants are
1681avaiable: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>, 2070available: C<IO::AIO::MADV_NORMAL>, C<IO::AIO::MADV_SEQUENTIAL>,
1682C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>, C<IO::AIO::MADV_DONTNEED>. 2071C<IO::AIO::MADV_RANDOM>, C<IO::AIO::MADV_WILLNEED>,
2072C<IO::AIO::MADV_DONTNEED>.
2073
2074If C<$offset> is negative, counts from the end. If C<$length> is negative,
2075the remaining length of the C<$scalar> is used. If possible, C<$length>
2076will be reduced to fit into the C<$scalar>.
1683 2077
1684On systems that do not implement C<posix_madvise>, this function returns 2078On systems that do not implement C<posix_madvise>, this function returns
1685ENOSYS, otherwise the return value of C<posix_madvise>. 2079ENOSYS, otherwise the return value of C<posix_madvise>.
1686 2080
1687=item IO::AIO::mprotect $scalar, $offset, $len, $protect 2081=item IO::AIO::mprotect $scalar, $offset, $len, $protect
1688 2082
1689Simply calls the C<mprotect> function on the preferably AIO::mmap'ed 2083Simply calls the C<mprotect> function on the preferably AIO::mmap'ed
1690$scalar (see its manpage for details). The following protect 2084$scalar (see its manpage for details). The following protect
1691constants are avaiable: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>, 2085constants are available: C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_READ>,
1692C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>. 2086C<IO::AIO::PROT_WRITE>, C<IO::AIO::PROT_EXEC>.
2087
2088If C<$offset> is negative, counts from the end. If C<$length> is negative,
2089the remaining length of the C<$scalar> is used. If possible, C<$length>
2090will be reduced to fit into the C<$scalar>.
1693 2091
1694On systems that do not implement C<mprotect>, this function returns 2092On systems that do not implement C<mprotect>, this function returns
1695ENOSYS, otherwise the return value of C<mprotect>. 2093ENOSYS, otherwise the return value of C<mprotect>.
1696 2094
1697=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset] 2095=item IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1698 2096
1699Memory-maps a file (or anonymous memory range) and attaches it to the 2097Memory-maps a file (or anonymous memory range) and attaches it to the
1700given C<$scalar>, which will act like a string scalar. 2098given C<$scalar>, which will act like a string scalar. Returns true on
2099success, and false otherwise.
1701 2100
2101The scalar must exist, but its contents do not matter - this means you
2102cannot use a nonexistant array or hash element. When in doubt, C<undef>
2103the scalar first.
2104
1702The only operations allowed on the scalar are C<substr>/C<vec> that don't 2105The only operations allowed on the mmapped scalar are C<substr>/C<vec>,
1703change the string length, and most read-only operations such as copying it 2106which don't change the string length, and most read-only operations such
1704or searching it with regexes and so on. 2107as copying it or searching it with regexes and so on.
1705 2108
1706Anything else is unsafe and will, at best, result in memory leaks. 2109Anything else is unsafe and will, at best, result in memory leaks.
1707 2110
1708The memory map associated with the C<$scalar> is automatically removed 2111The memory map associated with the C<$scalar> is automatically removed
1709when the C<$scalar> is destroyed, or when the C<IO::AIO::mmap> or 2112when the C<$scalar> is undef'd or destroyed, or when the C<IO::AIO::mmap>
1710C<IO::AIO::munmap> functions are called. 2113or C<IO::AIO::munmap> functions are called on it.
1711 2114
1712This calls the C<mmap>(2) function internally. See your system's manual 2115This calls the C<mmap>(2) function internally. See your system's manual
1713page for details on the C<$length>, C<$prot> and C<$flags> parameters. 2116page for details on the C<$length>, C<$prot> and C<$flags> parameters.
1714 2117
1715The C<$length> must be larger than zero and smaller than the actual 2118The C<$length> must be larger than zero and smaller than the actual
1716filesize. 2119filesize.
1717 2120
1718C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>, 2121C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>,
1719C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>, 2122C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
1720 2123
1721C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or 2124C<$flags> can be a combination of
1722C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when 2125C<IO::AIO::MAP_SHARED> or
1723not available, the are defined as 0): C<IO::AIO::MAP_ANONYMOUS> 2126C<IO::AIO::MAP_PRIVATE>,
2127or a number of system-specific flags (when not available, the are C<0>):
1724(which is set to C<MAP_ANON> if your system only provides this 2128C<IO::AIO::MAP_ANONYMOUS> (which is set to C<MAP_ANON> if your system only provides this constant),
1725constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>, 2129C<IO::AIO::MAP_LOCKED>,
1726C<IO::AIO::MAP_NORESERVE>, C<IO::AIO::MAP_POPULATE> or 2130C<IO::AIO::MAP_NORESERVE>,
2131C<IO::AIO::MAP_POPULATE>,
1727C<IO::AIO::MAP_NONBLOCK> 2132C<IO::AIO::MAP_NONBLOCK>,
2133C<IO::AIO::MAP_FIXED>,
2134C<IO::AIO::MAP_GROWSDOWN>,
2135C<IO::AIO::MAP_32BIT>,
2136C<IO::AIO::MAP_HUGETLB> or
2137C<IO::AIO::MAP_STACK>.
1728 2138
1729If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. 2139If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
1730 2140
1731C<$offset> is the offset from the start of the file - it generally must be 2141C<$offset> is the offset from the start of the file - it generally must be
1732a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>. 2142a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
1757 2167
1758Calls the C<munlockall> function. 2168Calls the C<munlockall> function.
1759 2169
1760On systems that do not implement C<munlockall>, this function returns 2170On systems that do not implement C<munlockall>, this function returns
1761ENOSYS, otherwise the return value of C<munlockall>. 2171ENOSYS, otherwise the return value of C<munlockall>.
2172
2173=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
2174
2175Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
2176C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
2177should be the file offset.
2178
2179C<$r_fh> and C<$w_fh> should not refer to the same file, as splice might
2180silently corrupt the data in this case.
2181
2182The following symbol flag values are available: C<IO::AIO::SPLICE_F_MOVE>,
2183C<IO::AIO::SPLICE_F_NONBLOCK>, C<IO::AIO::SPLICE_F_MORE> and
2184C<IO::AIO::SPLICE_F_GIFT>.
2185
2186See the C<splice(2)> manpage for details.
2187
2188=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2189
2190Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
2191description for C<IO::AIO::splice> above for details.
2192
2193=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2194
2195Attempts to query or change the pipe buffer size. Obviously works only
2196on pipes, and currently works only on GNU/Linux systems, and fails with
2197C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2198size on other systems, drop me a note.
2199
2200=item ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
2201
2202This is a direct interface to the Linux L<pipe2(2)> system call. If
2203C<$flags> is missing or C<0>, then this should be the same as a call to
2204perl's built-in C<pipe> function and create a new pipe, and works on
2205systems that lack the pipe2 syscall. On win32, this case invokes C<_pipe
2206(..., 4096, O_BINARY)>.
2207
2208If C<$flags> is non-zero, it tries to invoke the pipe2 system call with
2209the given flags (Linux 2.6.27, glibc 2.9).
2210
2211On success, the read and write file handles are returned.
2212
2213On error, nothing will be returned. If the pipe2 syscall is missing and
2214C<$flags> is non-zero, fails with C<ENOSYS>.
2215
2216Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
2217time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
2218C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported.
2219
2220Example: create a pipe race-free w.r.t. threads and fork:
2221
2222 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2223 or die "pipe2: $!\n";
2224
2225=item $fh = IO::AIO::eventfd ([$initval, [$flags]])
2226
2227This is a direct interface to the Linux L<eventfd(2)> system call. The
2228(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2229
2230On success, the new eventfd filehandle is returned, otherwise returns
2231C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
2232
2233Please refer to L<eventfd(2)> for more info on this call.
2234
2235The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
2236C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
1762 2237
1763=back 2238=back
1764 2239
1765=cut 2240=cut
1766 2241
1821 2296
1822=over 4 2297=over 4
1823 2298
1824=item IO::AIO::reinit 2299=item IO::AIO::reinit
1825 2300
1826Abondons all current requests and I/O threads and simply reinitialises all 2301Abandons all current requests and I/O threads and simply reinitialises all
1827data structures. This is not an operation suppported by any standards, but 2302data structures. This is not an operation supported by any standards, but
1828happens to work on GNU/Linux and some newer BSD systems. 2303happens to work on GNU/Linux and some newer BSD systems.
1829 2304
1830The only reasonable use for this function is to call it after forking, if 2305The only reasonable use for this function is to call it after forking, if
1831C<IO::AIO> was used in the parent. Calling it while IO::AIO is active in 2306C<IO::AIO> was used in the parent. Calling it while IO::AIO is active in
1832the process will result in undefined behaviour. Calling it at any time 2307the process will result in undefined behaviour. Calling it at any time

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines