1AIO(3)                User Contributed Perl Documentation               AIO(3)
2
3
4

NAME

6       IO::AIO - Asynchronous/Advanced Input/Output
7

SYNOPSIS

9        use IO::AIO;
10
11        aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
12           my $fh = shift
13              or die "/etc/passwd: $!";
14           ...
15        };
16
17        aio_unlink "/tmp/file", sub { };
18
19        aio_read $fh, 30000, 1024, $buffer, 0, sub {
20           $_[0] > 0 or die "read error: $!";
21        };
22
23        # version 2+ has request and group objects
24        use IO::AIO 2;
25
26        aioreq_pri 4; # give next request a very high priority
27        my $req = aio_unlink "/tmp/file", sub { };
28        $req->cancel; # cancel request if still in queue
29
30        my $grp = aio_group sub { print "all stats done\n" };
31        add $grp aio_stat "..." for ...;
32

DESCRIPTION

34       This module implements asynchronous I/O using whatever means your
35       operating system supports. It is implemented as an interface to
36       "libeio" (<http://software.schmorp.de/pkg/libeio.html>).
37
38       Asynchronous means that operations that can normally block your program
39       (e.g. reading from disk) will be done asynchronously: the operation
40       will still block, but you can do something else in the meantime. This
41       is extremely useful for programs that need to stay interactive even
42       when doing heavy I/O (GUI programs, high performance network servers
43       etc.), but can also be used to easily do operations in parallel that
44       are normally done sequentially, e.g. stat'ing many files, which is much
45       faster on a RAID volume or over NFS when you do a number of stat
46       operations concurrently.
47
48       While most of this works on all types of file descriptors (for example
49       sockets), using these functions on file descriptors that support
50       nonblocking operation (again, sockets, pipes etc.) is very inefficient.
51       Use an event loop for that (such as the EV module): IO::AIO will
52       naturally fit into such an event loop itself.
53
54       In this version, a number of threads are started that execute your
55       requests and signal their completion. You don't need thread support in
56       perl, and the threads created by this module will not be visible to
57       perl. In the future, this module might make use of the native aio
58       functions available on many operating systems. However, they are often
59       not well-supported or restricted (GNU/Linux doesn't allow them on
60       normal files currently, for example), and they would only support
61       aio_read and aio_write, so the remaining functionality would have to be
62       implemented using threads anyway.
63
64       In addition to asynchronous I/O, this module also exports some rather
65       arcane interfaces, such as "madvise" or linux's "splice" system call,
66       which is why the "A" in "AIO" can also mean advanced.
67
68       Although the module will work in the presence of other (Perl-) threads,
69       it is currently not reentrant in any way, so use appropriate locking
70       yourself, always call "poll_cb" from within the same thread, or never
71       call "poll_cb" (or other "aio_" functions) recursively.
72
73   EXAMPLE
74       This is a simple example that uses the EV module and loads /etc/passwd
75       asynchronously:
76
77          use EV;
78          use IO::AIO;
79
80          # register the IO::AIO callback with EV
81          my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
82
83          # queue the request to open /etc/passwd
84          aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
85             my $fh = shift
86                or die "error while opening: $!";
87
88             # stat'ing filehandles is generally non-blocking
89             my $size = -s $fh;
90
91             # queue a request to read the file
92             my $contents;
93             aio_read $fh, 0, $size, $contents, 0, sub {
94                $_[0] == $size
95                   or die "short read: $!";
96
97                close $fh;
98
99                # file contents now in $contents
100                print $contents;
101
102                # exit event loop and program
103                EV::break;
104             };
105          };
106
107          # possibly queue up other requests, or open GUI windows,
108          # check for sockets etc. etc.
109
110          # process events as long as there are some:
111          EV::run;
112

REQUEST ANATOMY AND LIFETIME

114       Every "aio_*" function creates a request. which is a C data structure
115       not directly visible to Perl.
116
117       If called in non-void context, every request function returns a Perl
118       object representing the request. In void context, nothing is returned,
119       which saves a bit of memory.
120
121       The perl object is a fairly standard ref-to-hash object. The hash
122       contents are not used by IO::AIO so you are free to store anything you
123       like in it.
124
125       During their existance, aio requests travel through the following
126       states, in order:
127
128       ready
129           Immediately after a request is created it is put into the ready
130           state, waiting for a thread to execute it.
131
132       execute
133           A thread has accepted the request for processing and is currently
134           executing it (e.g. blocking in read).
135
136       pending
137           The request has been executed and is waiting for result processing.
138
139           While request submission and execution is fully asynchronous,
140           result processing is not and relies on the perl interpreter calling
141           "poll_cb" (or another function with the same effect).
142
143       result
144           The request results are processed synchronously by "poll_cb".
145
146           The "poll_cb" function will process all outstanding aio requests by
147           calling their callbacks, freeing memory associated with them and
148           managing any groups they are contained in.
149
150       done
151           Request has reached the end of its lifetime and holds no resources
152           anymore (except possibly for the Perl object, but its connection to
153           the actual aio request is severed and calling its methods will
154           either do nothing or result in a runtime error).
155

FUNCTIONS

157   QUICK OVERVIEW
158       This section simply lists the prototypes most of the functions for
159       quick reference. See the following sections for function-by-function
160       documentation.
161
162          aio_wd $pathname, $callback->($wd)
163          aio_open $pathname, $flags, $mode, $callback->($fh)
164          aio_close $fh, $callback->($status)
165          aio_seek  $fh,$offset,$whence, $callback->($offs)
166          aio_read  $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
167          aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
168          aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
169          aio_readahead $fh,$offset,$length, $callback->($retval)
170          aio_stat  $fh_or_path, $callback->($status)
171          aio_lstat $fh, $callback->($status)
172          aio_statvfs $fh_or_path, $callback->($statvfs)
173          aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
174          aio_chown $fh_or_path, $uid, $gid, $callback->($status)
175          aio_chmod $fh_or_path, $mode, $callback->($status)
176          aio_truncate $fh_or_path, $offset, $callback->($status)
177          aio_allocate $fh, $mode, $offset, $len, $callback->($status)
178          aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
179          aio_unlink $pathname, $callback->($status)
180          aio_mknod $pathname, $mode, $dev, $callback->($status)
181          aio_link $srcpath, $dstpath, $callback->($status)
182          aio_symlink $srcpath, $dstpath, $callback->($status)
183          aio_readlink $pathname, $callback->($link)
184          aio_realpath $pathname, $callback->($path)
185          aio_rename $srcpath, $dstpath, $callback->($status)
186          aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
187          aio_mkdir $pathname, $mode, $callback->($status)
188          aio_rmdir $pathname, $callback->($status)
189          aio_readdir $pathname, $callback->($entries)
190          aio_readdirx $pathname, $flags, $callback->($entries, $flags)
191             IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
192             IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
193          aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
194          aio_load $pathname, $data, $callback->($status)
195          aio_copy $srcpath, $dstpath, $callback->($status)
196          aio_move $srcpath, $dstpath, $callback->($status)
197          aio_rmtree $pathname, $callback->($status)
198          aio_fcntl $fh, $cmd, $arg, $callback->($status)
199          aio_ioctl $fh, $request, $buf, $callback->($status)
200          aio_sync $callback->($status)
201          aio_syncfs $fh, $callback->($status)
202          aio_fsync $fh, $callback->($status)
203          aio_fdatasync $fh, $callback->($status)
204          aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
205          aio_pathsync $pathname, $callback->($status)
206          aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
207          aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
208          aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
209          aio_mlockall $flags, $callback->($status)
210          aio_group $callback->(...)
211          aio_nop $callback->()
212
213          $prev_pri = aioreq_pri [$pri]
214          aioreq_nice $pri_adjust
215
216          IO::AIO::poll_wait
217          IO::AIO::poll_cb
218          IO::AIO::poll
219          IO::AIO::flush
220          IO::AIO::max_poll_reqs $nreqs
221          IO::AIO::max_poll_time $seconds
222          IO::AIO::min_parallel $nthreads
223          IO::AIO::max_parallel $nthreads
224          IO::AIO::max_idle $nthreads
225          IO::AIO::idle_timeout $seconds
226          IO::AIO::max_outstanding $maxreqs
227          IO::AIO::nreqs
228          IO::AIO::nready
229          IO::AIO::npending
230          IO::AIO::reinit
231
232          $nfd = IO::AIO::get_fdlimit
233          IO::AIO::min_fdlimit $nfd
234
235          IO::AIO::sendfile $ofh, $ifh, $offset, $count
236          IO::AIO::fadvise $fh, $offset, $len, $advice
237
238          IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
239          IO::AIO::munmap $scalar
240          IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
241          IO::AIO::madvise $scalar, $offset, $length, $advice
242          IO::AIO::mprotect $scalar, $offset, $length, $protect
243          IO::AIO::munlock $scalar, $offset = 0, $length = undef
244          IO::AIO::munlockall
245
246          # stat extensions
247          $counter = IO::AIO::st_gen
248          $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
249          ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
250          $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
251          $seconds = IO::AIO::st_btimesec
252          ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
253
254          # very much unportable syscalls
255          IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
256          IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
257          IO::AIO::tee $r_fh, $w_fh, $length, $flags
258          $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
259          ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
260          $fh = IO::AIO::memfd_create $pathname[, $flags]
261          $fh = IO::AIO::eventfd [$initval, [$flags]]
262          $fh = IO::AIO::timerfd_create $clockid[, $flags]
263          ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
264          ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
265
266   API NOTES
267       All the "aio_*" calls are more or less thin wrappers around the syscall
268       with the same name (sans "aio_"). The arguments are similar or
269       identical, and they all accept an additional (and optional) $callback
270       argument which must be a code reference. This code reference will be
271       called after the syscall has been executed in an asynchronous fashion.
272       The results of the request will be passed as arguments to the callback
273       (and, if an error occured, in $!) - for most requests the syscall
274       return code (e.g.  most syscalls return "-1" on error, unlike perl,
275       which usually delivers "false").
276
277       Some requests (such as "aio_readdir") pass the actual results and
278       communicate failures by passing "undef".
279
280       All functions expecting a filehandle keep a copy of the filehandle
281       internally until the request has finished.
282
283       All functions return request objects of type IO::AIO::REQ that allow
284       further manipulation of those requests while they are in-flight.
285
286       The pathnames you pass to these routines should be absolute. The reason
287       for this is that at the time the request is being executed, the current
288       working directory could have changed. Alternatively, you can make sure
289       that you never change the current working directory anywhere in the
290       program and then use relative paths. You can also take advantage of
291       IO::AIOs working directory abstraction, that lets you specify paths
292       relative to some previously-opened "working directory object" - see the
293       description of the "IO::AIO::WD" class later in this document.
294
295       To encode pathnames as octets, either make sure you either: a) always
296       pass in filenames you got from outside (command line, readdir etc.)
297       without tinkering, b) are in your native filesystem encoding, c) use
298       the Encode module and encode your pathnames to the locale (or other)
299       encoding in effect in the user environment, d) use
300       Glib::filename_from_unicode on unicode filenames or e) use something
301       else to ensure your scalar has the correct contents.
302
303       This works, btw. independent of the internal UTF-8 bit, which IO::AIO
304       handles correctly whether it is set or not.
305
306   AIO REQUEST FUNCTIONS
307       $prev_pri = aioreq_pri [$pri]
308           Returns the priority value that would be used for the next request
309           and, if $pri is given, sets the priority for the next aio request.
310
311           The default priority is 0, the minimum and maximum priorities are
312           "-4" and 4, respectively. Requests with higher priority will be
313           serviced first.
314
315           The priority will be reset to 0 after each call to one of the
316           "aio_*" functions.
317
318           Example: open a file with low priority, then read something from it
319           with higher priority so the read request is serviced before other
320           low priority open requests (potentially spamming the cache):
321
322              aioreq_pri -3;
323              aio_open ..., sub {
324                 return unless $_[0];
325
326                 aioreq_pri -2;
327                 aio_read $_[0], ..., sub {
328                    ...
329                 };
330              };
331
332       aioreq_nice $pri_adjust
333           Similar to "aioreq_pri", but subtracts the given value from the
334           current priority, so the effect is cumulative.
335
336       aio_open $pathname, $flags, $mode, $callback->($fh)
337           Asynchronously open or create a file and call the callback with a
338           newly created filehandle for the file (or "undef" in case of an
339           error).
340
341           The pathname passed to "aio_open" must be absolute. See API NOTES,
342           above, for an explanation.
343
344           The $flags argument is a bitmask. See the "Fcntl" module for a
345           list. They are the same as used by "sysopen".
346
347           Likewise, $mode specifies the mode of the newly created file, if it
348           didn't exist and "O_CREAT" has been given, just like perl's
349           "sysopen", except that it is mandatory (i.e. use 0 if you don't
350           create new files, and 0666 or 0777 if you do). Note that the $mode
351           will be modified by the umask in effect then the request is being
352           executed, so better never change the umask.
353
354           Example:
355
356              aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
357                 if ($_[0]) {
358                    print "open successful, fh is $_[0]\n";
359                    ...
360                 } else {
361                    die "open failed: $!\n";
362                 }
363              };
364
365           In addition to all the common open modes/flags ("O_RDONLY",
366           "O_WRONLY", "O_RDWR", "O_CREAT", "O_TRUNC", "O_EXCL" and
367           "O_APPEND"), the following POSIX and non-POSIX constants are
368           available (missing ones on your system are, as usual, 0):
369
370           "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
371           "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
372           "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", "O_TTY_INIT"
373           and "O_ACCMODE".
374
375       aio_close $fh, $callback->($status)
376           Asynchronously close a file and call the callback with the result
377           code.
378
379           Unfortunately, you can't do this to perl. Perl insists very
380           strongly on closing the file descriptor associated with the
381           filehandle itself.
382
383           Therefore, "aio_close" will not close the filehandle - instead it
384           will use dup2 to overwrite the file descriptor with the write-end
385           of a pipe (the pipe fd will be created on demand and will be
386           cached).
387
388           Or in other words: the file descriptor will be closed, but it will
389           not be free for reuse until the perl filehandle is closed.
390
391       aio_seek $fh, $offset, $whence, $callback->($offs)
392           Seeks the filehandle to the new $offset, similarly to perl's
393           "sysseek". The $whence can use the traditional values (0 for
394           "IO::AIO::SEEK_SET", 1 for "IO::AIO::SEEK_CUR" or 2 for
395           "IO::AIO::SEEK_END").
396
397           The resulting absolute offset will be passed to the callback, or
398           "-1" in case of an error.
399
400           In theory, the $whence constants could be different than the
401           corresponding values from Fcntl, but perl guarantees they are the
402           same, so don't panic.
403
404           As a GNU/Linux (and maybe Solaris) extension, also the constants
405           "IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if
406           they could be found. No guarantees about suitability for use in
407           "aio_seek" or Perl's "sysseek" can be made though, although I would
408           naively assume they "just work".
409
410       aio_read  $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
411       aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
412           Reads or writes $length bytes from or to the specified $fh and
413           $offset into the scalar given by $data and offset $dataoffset and
414           calls the callback with the actual number of bytes transferred (or
415           -1 on error, just like the syscall).
416
417           "aio_read" will, like "sysread", shrink or grow the $data scalar to
418           offset plus the actual number of bytes read.
419
420           If $offset is undefined, then the current file descriptor offset
421           will be used (and updated), otherwise the file descriptor offset
422           will not be changed by these calls.
423
424           If $length is undefined in "aio_write", use the remaining length of
425           $data.
426
427           If $dataoffset is less than zero, it will be counted from the end
428           of $data.
429
430           The $data scalar MUST NOT be modified in any way while the request
431           is outstanding. Modifying it can result in segfaults or World War
432           III (if the necessary/optional hardware is installed).
433
434           Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
435           offset 0 within the scalar:
436
437              aio_read $fh, 7, 15, $buffer, 0, sub {
438                 $_[0] > 0 or die "read error: $!";
439                 print "read $_[0] bytes: <$buffer>\n";
440              };
441
442       aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
443           Tries to copy $length bytes from $in_fh to $out_fh. It starts
444           reading at byte offset $in_offset, and starts writing at the
445           current file offset of $out_fh. Because of that, it is not safe to
446           issue more than one "aio_sendfile" per $out_fh, as they will
447           interfere with each other. The same $in_fh works fine though, as
448           this function does not move or use the file offset of $in_fh.
449
450           Please note that "aio_sendfile" can read more bytes from $in_fh
451           than are written, and there is no way to find out how many more
452           bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
453           only provides the number of bytes written to $out_fh. Only if the
454           result value equals $length one can assume that $length bytes have
455           been read.
456
457           Unlike with other "aio_" functions, it makes a lot of sense to use
458           "aio_sendfile" on non-blocking sockets, as long as one end
459           (typically the $in_fh) is a file - the file I/O will then be
460           asynchronous, while the socket I/O will be non-blocking. Note,
461           however, that you can run into a trap where "aio_sendfile" reads
462           some data with readahead, then fails to write all data, and when
463           the socket is ready the next time, the data in the cache is already
464           lost, forcing "aio_sendfile" to again hit the disk. Explicit
465           "aio_read" + "aio_write" let's you better control resource usage.
466
467           This call tries to make use of a native "sendfile"-like syscall to
468           provide zero-copy operation. For this to work, $out_fh should refer
469           to a socket, and $in_fh should refer to an mmap'able file.
470
471           If a native sendfile cannot be found or it fails with "ENOSYS",
472           "EINVAL", "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
473           "ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
474           any type of filehandle regardless of the limitations of the
475           operating system.
476
477           As native sendfile syscalls (as practically any non-POSIX interface
478           hacked together in a hurry to improve benchmark numbers) tend to be
479           rather buggy on many systems, this implementation tries to work
480           around some known bugs in Linux and FreeBSD kernels (probably
481           others, too), but that might fail, so you really really should
482           check the return value of "aio_sendfile" - fewer bytes than
483           expected might have been transferred.
484
485       aio_readahead $fh,$offset,$length, $callback->($retval)
486           "aio_readahead" populates the page cache with data from a file so
487           that subsequent reads from that file will not block on disk I/O.
488           The $offset argument specifies the starting point from which data
489           is to be read and $length specifies the number of bytes to be read.
490           I/O is performed in whole pages, so that offset is effectively
491           rounded down to a page boundary and bytes are read up to the next
492           page boundary greater than or equal to (off-set+length).
493           "aio_readahead" does not read beyond the end of the file. The
494           current file offset of the file is left unchanged.
495
496           If that syscall doesn't exist (likely if your kernel isn't Linux)
497           it will be emulated by simply reading the data, which would have a
498           similar effect.
499
500       aio_stat  $fh_or_path, $callback->($status)
501       aio_lstat $fh, $callback->($status)
502           Works almost exactly like perl's "stat" or "lstat" in void context.
503           The callback will be called after the stat and the results will be
504           available using "stat _" or "-s _" and other tests (with the
505           exception of "-B" and "-T").
506
507           The pathname passed to "aio_stat" must be absolute. See API NOTES,
508           above, for an explanation.
509
510           Currently, the stats are always 64-bit-stats, i.e. instead of
511           returning an error when stat'ing a large file, the results will be
512           silently truncated unless perl itself is compiled with large file
513           support.
514
515           To help interpret the mode and dev/rdev stat values, IO::AIO offers
516           the following constants and functions (if not implemented, the
517           constants will be 0 and the functions will either "croak" or fall
518           back on traditional behaviour).
519
520           "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
521           "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
522           "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
523
524           To access higher resolution stat timestamps, see "SUBSECOND STAT
525           TIME ACCESS".
526
527           Example: Print the length of /etc/passwd:
528
529              aio_stat "/etc/passwd", sub {
530                 $_[0] and die "stat failed: $!";
531                 print "size is ", -s _, "\n";
532              };
533
534       aio_statvfs $fh_or_path, $callback->($statvfs)
535           Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
536           whether a file handle or path was passed.
537
538           On success, the callback is passed a hash reference with the
539           following members: "bsize", "frsize", "blocks", "bfree", "bavail",
540           "files", "ffree", "favail", "fsid", "flag" and "namemax". On
541           failure, "undef" is passed.
542
543           The following POSIX IO::AIO::ST_* constants are defined:
544           "ST_RDONLY" and "ST_NOSUID".
545
546           The following non-POSIX IO::AIO::ST_* flag masks are defined to
547           their correct value when available, or to 0 on systems that do not
548           support them:  "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
549           "ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
550           "ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
551
552           Example: stat "/wd" and dump out the data if successful.
553
554              aio_statvfs "/wd", sub {
555                 my $f = $_[0]
556                    or die "statvfs: $!";
557
558                 use Data::Dumper;
559                 say Dumper $f;
560              };
561
562              # result:
563              {
564                 bsize   => 1024,
565                 bfree   => 4333064312,
566                 blocks  => 10253828096,
567                 files   => 2050765568,
568                 flag    => 4096,
569                 favail  => 2042092649,
570                 bavail  => 4333064312,
571                 ffree   => 2042092649,
572                 namemax => 255,
573                 frsize  => 1024,
574                 fsid    => 1810
575              }
576
577       aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
578           Works like perl's "utime" function (including the special case of
579           $atime and $mtime being undef). Fractional times are supported if
580           the underlying syscalls support them.
581
582           When called with a pathname, uses utimensat(2) or utimes(2) if
583           available, otherwise utime(2). If called on a file descriptor, uses
584           futimens(2) or futimes(2) if available, otherwise returns ENOSYS,
585           so this is not portable.
586
587           Examples:
588
589              # set atime and mtime to current time (basically touch(1)):
590              aio_utime "path", undef, undef;
591              # set atime to current time and mtime to beginning of the epoch:
592              aio_utime "path", time, undef; # undef==0
593
594       aio_chown $fh_or_path, $uid, $gid, $callback->($status)
595           Works like perl's "chown" function, except that "undef" for either
596           $uid or $gid is being interpreted as "do not change" (but -1 can
597           also be used).
598
599           Examples:
600
601              # same as "chown root path" in the shell:
602              aio_chown "path", 0, -1;
603              # same as above:
604              aio_chown "path", 0, undef;
605
606       aio_truncate $fh_or_path, $offset, $callback->($status)
607           Works like truncate(2) or ftruncate(2).
608
609       aio_allocate $fh, $mode, $offset, $len, $callback->($status)
610           Allocates or frees disk space according to the $mode argument. See
611           the linux "fallocate" documentation for details.
612
613           $mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
614           space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
615           IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
616
617           IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
618           (without leaving a hole), "FALLOC_FL_ZERO_RANGE", to zero a range,
619           "FALLOC_FL_INSERT_RANGE" to insert a range and
620           "FALLOC_FL_UNSHARE_RANGE" to unshare shared blocks (see your
621           fallocate(2) manpage).
622
623           The file system block size used by "fallocate" is presumably the
624           "f_bsize" returned by "statvfs", but different filesystems and
625           filetypes can dictate other limitations.
626
627           If "fallocate" isn't available or cannot be emulated (currently no
628           emulation will be attempted), passes "-1" and sets $! to "ENOSYS".
629
630       aio_chmod $fh_or_path, $mode, $callback->($status)
631           Works like perl's "chmod" function.
632
633       aio_unlink $pathname, $callback->($status)
634           Asynchronously unlink (delete) a file and call the callback with
635           the result code.
636
637       aio_mknod $pathname, $mode, $dev, $callback->($status)
638           [EXPERIMENTAL]
639
640           Asynchronously create a device node (or fifo). See mknod(2).
641
642           The only (POSIX-) portable way of calling this function is:
643
644              aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
645
646           See "aio_stat" for info about some potentially helpful extra
647           constants and functions.
648
649       aio_link $srcpath, $dstpath, $callback->($status)
650           Asynchronously create a new link to the existing object at $srcpath
651           at the path $dstpath and call the callback with the result code.
652
653       aio_symlink $srcpath, $dstpath, $callback->($status)
654           Asynchronously create a new symbolic link to the existing object at
655           $srcpath at the path $dstpath and call the callback with the result
656           code.
657
658       aio_readlink $pathname, $callback->($link)
659           Asynchronously read the symlink specified by $path and pass it to
660           the callback. If an error occurs, nothing or undef gets passed to
661           the callback.
662
663       aio_realpath $pathname, $callback->($path)
664           Asynchronously make the path absolute and resolve any symlinks in
665           $path. The resulting path only consists of directories (same as
666           Cwd::realpath).
667
668           This request can be used to get the absolute path of the current
669           working directory by passing it a path of . (a single dot).
670
671       aio_rename $srcpath, $dstpath, $callback->($status)
672           Asynchronously rename the object at $srcpath to $dstpath, just as
673           rename(2) and call the callback with the result code.
674
675           On systems that support the AIO::WD working directory abstraction
676           natively, the case "[$wd, "."]" as $srcpath is specialcased -
677           instead of failing, "rename" is called on the absolute path of $wd.
678
679       aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
680           Basically a version of "aio_rename" with an additional $flags
681           argument. Calling this with "$flags=0" is the same as calling
682           "aio_rename".
683
684           Non-zero flags are currently only supported on GNU/Linux systems
685           that support renameat2. Other systems fail with "ENOSYS" in this
686           case.
687
688           The following constants are available (missing ones are, as usual
689           0), see renameat2(2) for details:
690
691           "IO::AIO::RENAME_NOREPLACE", "IO::AIO::RENAME_EXCHANGE" and
692           "IO::AIO::RENAME_WHITEOUT".
693
694       aio_mkdir $pathname, $mode, $callback->($status)
695           Asynchronously mkdir (create) a directory and call the callback
696           with the result code. $mode will be modified by the umask at the
697           time the request is executed, so do not change your umask.
698
699       aio_rmdir $pathname, $callback->($status)
700           Asynchronously rmdir (delete) a directory and call the callback
701           with the result code.
702
703           On systems that support the AIO::WD working directory abstraction
704           natively, the case "[$wd, "."]" is specialcased - instead of
705           failing, "rmdir" is called on the absolute path of $wd.
706
707       aio_readdir $pathname, $callback->($entries)
708           Unlike the POSIX call of the same name, "aio_readdir" reads an
709           entire directory (i.e. opendir + readdir + closedir). The entries
710           will not be sorted, and will NOT include the "." and ".." entries.
711
712           The callback is passed a single argument which is either "undef" or
713           an array-ref with the filenames.
714
715       aio_readdirx $pathname, $flags, $callback->($entries, $flags)
716           Quite similar to "aio_readdir", but the $flags argument allows one
717           to tune behaviour and output format. In case of an error, $entries
718           will be "undef".
719
720           The flags are a combination of the following constants, ORed
721           together (the flags will also be passed to the callback, possibly
722           modified):
723
724           IO::AIO::READDIR_DENTS
725               Normally the callback gets an arrayref consisting of names only
726               (as with "aio_readdir"). If this flag is set, then the callback
727               gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
728               describing a single directory entry in more detail:
729
730               $name is the name of the entry.
731
732               $type is one of the "IO::AIO::DT_xxx" constants:
733
734               "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
735               "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
736               "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
737
738               "IO::AIO::DT_UNKNOWN" means just that: readdir does not know.
739               If you need to know, you have to run stat yourself. Also, for
740               speed/memory reasons, the $type scalars are read-only: you must
741               not modify them.
742
743               $inode is the inode number (which might not be exact on systems
744               with 64 bit inode numbers and 32 bit perls). This field has
745               unspecified content on systems that do not deliver the inode
746               information.
747
748           IO::AIO::READDIR_DIRS_FIRST
749               When this flag is set, then the names will be returned in an
750               order where likely directories come first, in optimal stat
751               order. This is useful when you need to quickly find
752               directories, or you want to find all directories while avoiding
753               to stat() each entry.
754
755               If the system returns type information in readdir, then this is
756               used to find directories directly. Otherwise, likely
757               directories are names beginning with ".", or otherwise names
758               with no dots, of which names with short names are tried first.
759
760           IO::AIO::READDIR_STAT_ORDER
761               When this flag is set, then the names will be returned in an
762               order suitable for stat()'ing each one. That is, when you plan
763               to stat() most or all files in the given directory, then the
764               returned order will likely be faster.
765
766               If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
767               specified, then the likely dirs come first, resulting in a less
768               optimal stat order for stat'ing all entries, but likely a more
769               optimal order for finding subdirectories.
770
771           IO::AIO::READDIR_FOUND_UNKNOWN
772               This flag should not be set when calling "aio_readdirx".
773               Instead, it is being set by "aio_readdirx", when any of the
774               $type's found were "IO::AIO::DT_UNKNOWN". The absence of this
775               flag therefore indicates that all $type's are known, which can
776               be used to speed up some algorithms.
777
778       aio_slurp $pathname, $offset, $length, $data, $callback->($status)
779           Opens, reads and closes the given file. The data is put into $data,
780           which is resized as required.
781
782           If $offset is negative, then it is counted from the end of the
783           file.
784
785           If $length is zero, then the remaining length of the file is used.
786           Also, in this case, the same limitations to modifying $data apply
787           as when IO::AIO::mmap is used, i.e. it must only be modified in-
788           place with "substr". If the size of the file is known, specifying a
789           non-zero $length results in a performance advantage.
790
791           This request is similar to the older "aio_load" request, but since
792           it is a single request, it might be more efficient to use.
793
794           Example: load /etc/passwd into $passwd.
795
796              my $passwd;
797              aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
798                 $_[0] >= 0
799                    or die "/etc/passwd: $!\n";
800
801                 printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
802                 print $passwd;
803              };
804              IO::AIO::flush;
805
806       aio_load $pathname, $data, $callback->($status)
807           This is a composite request that tries to fully load the given file
808           into memory. Status is the same as with aio_read.
809
810           Using "aio_slurp" might be more efficient, as it is a single
811           request.
812
813       aio_copy $srcpath, $dstpath, $callback->($status)
814           Try to copy the file (directories not supported as either source or
815           destination) from $srcpath to $dstpath and call the callback with a
816           status of 0 (ok) or "-1" (error, see $!).
817
818           Existing destination files will be truncated.
819
820           This is a composite request that creates the destination file with
821           mode 0200 and copies the contents of the source file into it using
822           "aio_sendfile", followed by restoring atime, mtime, access mode and
823           uid/gid, in that order.
824
825           If an error occurs, the partial destination file will be unlinked,
826           if possible, except when setting atime, mtime, access mode and
827           uid/gid, where errors are being ignored.
828
829       aio_move $srcpath, $dstpath, $callback->($status)
830           Try to move the file (directories not supported as either source or
831           destination) from $srcpath to $dstpath and call the callback with a
832           status of 0 (ok) or "-1" (error, see $!).
833
834           This is a composite request that tries to rename(2) the file first;
835           if rename fails with "EXDEV", it copies the file with "aio_copy"
836           and, if that is successful, unlinks the $srcpath.
837
838       aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
839           Scans a directory (similar to "aio_readdir") but additionally tries
840           to efficiently separate the entries of directory $path into two
841           sets of names, directories you can recurse into (directories), and
842           ones you cannot recurse into (everything else, including symlinks
843           to directories).
844
845           "aio_scandir" is a composite request that generates many sub
846           requests.  $maxreq specifies the maximum number of outstanding aio
847           requests that this function generates. If it is "<= 0", then a
848           suitable default will be chosen (currently 4).
849
850           On error, the callback is called without arguments, otherwise it
851           receives two array-refs with path-relative entry names.
852
853           Example:
854
855              aio_scandir $dir, 0, sub {
856                 my ($dirs, $nondirs) = @_;
857                 print "real directories: @$dirs\n";
858                 print "everything else: @$nondirs\n";
859              };
860
861           Implementation notes.
862
863           The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
864           can.
865
866           If readdir returns file type information, then this is used
867           directly to find directories.
868
869           Otherwise, after reading the directory, the modification time, size
870           etc.  of the directory before and after the readdir is checked, and
871           if they match (and isn't the current time), the link count will be
872           used to decide how many entries are directories (if >= 2).
873           Otherwise, no knowledge of the number of subdirectories will be
874           assumed.
875
876           Then entries will be sorted into likely directories a non-initial
877           dot currently) and likely non-directories (see "aio_readdirx").
878           Then every entry plus an appended "/." will be "stat"'ed, likely
879           directories first, in order of their inode numbers. If that
880           succeeds, it assumes that the entry is a directory or a symlink to
881           directory (which will be checked separately). This is often faster
882           than stat'ing the entry itself because filesystems might detect the
883           type of the entry without reading the inode data (e.g. ext2fs
884           filetype feature), even on systems that cannot return the filetype
885           information on readdir.
886
887           If the known number of directories (link count - 2) has been
888           reached, the rest of the entries is assumed to be non-directories.
889
890           This only works with certainty on POSIX (= UNIX) filesystems, which
891           fortunately are the vast majority of filesystems around.
892
893           It will also likely work on non-POSIX filesystems with reduced
894           efficiency as those tend to return 0 or 1 as link counts, which
895           disables the directory counting heuristic.
896
897       aio_rmtree $pathname, $callback->($status)
898           Delete a directory tree starting (and including) $path, return the
899           status of the final "rmdir" only. This is a composite request that
900           uses "aio_scandir" to recurse into and rmdir directories, and
901           unlink everything else.
902
903       aio_fcntl $fh, $cmd, $arg, $callback->($status)
904       aio_ioctl $fh, $request, $buf, $callback->($status)
905           These work just like the "fcntl" and "ioctl" built-in functions,
906           except they execute asynchronously and pass the return value to the
907           callback.
908
909           Both calls can be used for a lot of things, some of which make more
910           sense to run asynchronously in their own thread, while some others
911           make less sense. For example, calls that block waiting for external
912           events, such as locking, will also lock down an I/O thread while it
913           is waiting, which can deadlock the whole I/O system. At the same
914           time, there might be no alternative to using a thread to wait.
915
916           So in general, you should only use these calls for things that do
917           (filesystem) I/O, not for things that wait for other events
918           (network, other processes), although if you are careful and know
919           what you are doing, you still can.
920
921           The following constants are available and can be used for normal
922           "ioctl" and "fcntl" as well (missing ones are, as usual 0):
923
924           "F_DUPFD_CLOEXEC",
925
926           "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
927
928           "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
929           "FIDEDUPERANGE".
930
931           "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
932           "F_SEAL_GROW" and "F_SEAL_WRITE".
933
934           "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
935           "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
936
937           "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
938           "FS_IOC_SET_ENCRYPTION_POLICY", "FS_IOC_GET_ENCRYPTION_PWSALT",
939           "FS_IOC_GET_ENCRYPTION_POLICY", "FS_KEY_DESCRIPTOR_SIZE".
940
941           "FS_SECRM_FL", "FS_UNRM_FL", "FS_COMPR_FL", "FS_SYNC_FL",
942           "FS_IMMUTABLE_FL", "FS_APPEND_FL", "FS_NODUMP_FL", "FS_NOATIME_FL",
943           "FS_DIRTY_FL", "FS_COMPRBLK_FL", "FS_NOCOMP_FL", "FS_ENCRYPT_FL",
944           "FS_BTREE_FL", "FS_INDEX_FL", "FS_JOURNAL_DATA_FL", "FS_NOTAIL_FL",
945           "FS_DIRSYNC_FL", "FS_TOPDIR_FL", "FS_FL_USER_MODIFIABLE".
946
947           "FS_XFLAG_REALTIME", "FS_XFLAG_PREALLOC", "FS_XFLAG_IMMUTABLE",
948           "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
949           "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
950           "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
951           "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
952           "FS_XFLAG_HASATTR",
953
954       aio_sync $callback->($status)
955           Asynchronously call sync and call the callback when finished.
956
957       aio_fsync $fh, $callback->($status)
958           Asynchronously call fsync on the given filehandle and call the
959           callback with the fsync result code.
960
961       aio_fdatasync $fh, $callback->($status)
962           Asynchronously call fdatasync on the given filehandle and call the
963           callback with the fdatasync result code.
964
965           If this call isn't available because your OS lacks it or it
966           couldn't be detected, it will be emulated by calling "fsync"
967           instead.
968
969       aio_syncfs $fh, $callback->($status)
970           Asynchronously call the syncfs syscall to sync the filesystem
971           associated to the given filehandle and call the callback with the
972           syncfs result code. If syncfs is not available, calls sync(), but
973           returns "-1" and sets errno to "ENOSYS" nevertheless.
974
975       aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
976           Sync the data portion of the file specified by $offset and $length
977           to disk (but NOT the metadata), by calling the Linux-specific
978           sync_file_range call. If sync_file_range is not available or it
979           returns ENOSYS, then fdatasync or fsync is being substituted.
980
981           $flags can be a combination of
982           "IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
983           "IO::AIO::SYNC_FILE_RANGE_WRITE" and
984           "IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
985           manpage for details.
986
987       aio_pathsync $pathname, $callback->($status)
988           This request tries to open, fsync and close the given path. This is
989           a composite request intended to sync directories after directory
990           operations (E.g. rename). This might not work on all operating
991           systems or have any specific effect, but usually it makes sure that
992           directory changes get written to disc. It works for anything that
993           can be opened for read-only, not just directories.
994
995           Future versions of this function might fall back to other methods
996           when "fsync" on the directory fails (such as calling "sync").
997
998           Passes 0 when everything went ok, and "-1" on error.
999
1000       aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC,
1001       $callback->($status)
1002           This is a rather advanced IO::AIO call, which only works on
1003           mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
1004           also works on data scalars managed by the Sys::Mmap or Mmap
1005           modules, note that the scalar must only be modified in-place while
1006           an aio operation is pending on it).
1007
1008           It calls the "msync" function of your OS, if available, with the
1009           memory area starting at $offset in the string and ending $length
1010           bytes later. If $length is negative, counts from the end, and if
1011           $length is "undef", then it goes till the end of the string. The
1012           flags can be either "IO::AIO::MS_ASYNC" or "IO::AIO::MS_SYNC", plus
1013           an optional "IO::AIO::MS_INVALIDATE".
1014
1015       aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
1016       $callback->($status)
1017           This is a rather advanced IO::AIO call, which works best on
1018           mmap(2)ed scalars.
1019
1020           It touches (reads or writes) all memory pages in the specified
1021           range inside the scalar. All caveats and parameters are the same as
1022           for "aio_msync", above, except for flags, which must be either 0
1023           (which reads all pages and ensures they are instantiated) or
1024           "IO::AIO::MT_MODIFY", which modifies the memory pages (by reading
1025           and writing an octet from it, which dirties the page).
1026
1027       aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1028           This is a rather advanced IO::AIO call, which works best on
1029           mmap(2)ed scalars.
1030
1031           It reads in all the pages of the underlying storage into memory (if
1032           any) and locks them, so they are not getting swapped/paged out or
1033           removed.
1034
1035           If $length is undefined, then the scalar will be locked till the
1036           end.
1037
1038           On systems that do not implement "mlock", this function returns
1039           "-1" and sets errno to "ENOSYS".
1040
1041           Note that the corresponding "munlock" is synchronous and is
1042           documented under "MISCELLANEOUS FUNCTIONS".
1043
1044           Example: open a file, mmap and mlock it - both will be undone when
1045           $data gets destroyed.
1046
1047              open my $fh, "<", $path or die "$path: $!";
1048              my $data;
1049              IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1050              aio_mlock $data; # mlock in background
1051
1052       aio_mlockall $flags, $callback->($status)
1053           Calls the "mlockall" function with the given $flags (a combination
1054           of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
1055           "IO::AIO::MCL_ONFAULT").
1056
1057           On systems that do not implement "mlockall", this function returns
1058           "-1" and sets errno to "ENOSYS". Similarly, flag combinations not
1059           supported by the system result in a return value of "-1" with errno
1060           being set to "EINVAL".
1061
1062           Note that the corresponding "munlockall" is synchronous and is
1063           documented under "MISCELLANEOUS FUNCTIONS".
1064
1065           Example: asynchronously lock all current and future pages into
1066           memory.
1067
1068              aio_mlockall IO::AIO::MCL_FUTURE;
1069
1070       aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1071           Queries the extents of the given file (by calling the Linux
1072           "FIEMAP" ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt>
1073           for details). If the ioctl is not available on your OS, then this
1074           request will fail with "ENOSYS".
1075
1076           $start is the starting offset to query extents for, $length is the
1077           size of the range to query - if it is "undef", then the whole file
1078           will be queried.
1079
1080           $flags is a combination of flags ("IO::AIO::FIEMAP_FLAG_SYNC" or
1081           "IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
1082           also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
1083           query the data portion.
1084
1085           $count is the maximum number of extent records to return. If it is
1086           "undef", then IO::AIO queries all extents of the range. As a very
1087           special case, if it is 0, then the callback receives the number of
1088           extents instead of the extents themselves (which is unreliable, see
1089           below).
1090
1091           If an error occurs, the callback receives no arguments. The special
1092           "errno" value "IO::AIO::EBADR" is available to test for flag
1093           errors.
1094
1095           Otherwise, the callback receives an array reference with extent
1096           structures. Each extent structure is an array reference itself,
1097           with the following members:
1098
1099              [$logical, $physical, $length, $flags]
1100
1101           Flags is any combination of the following flag values (typically
1102           either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
1103
1104           "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
1105           "IO::AIO::FIEMAP_EXTENT_DELALLOC",
1106           "IO::AIO::FIEMAP_EXTENT_ENCODED",
1107           "IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
1108           "IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
1109           "IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
1110           "IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
1111           "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
1112           or "IO::AIO::FIEMAP_EXTENT_SHARED".
1113
1114           At the time of this writing (Linux 3.2), this request is unreliable
1115           unless $count is "undef", as the kernel has all sorts of bugs
1116           preventing it to return all extents of a range for files with a
1117           large number of extents. The code (only) works around all these
1118           issues if $count is "undef".
1119
1120       aio_group $callback->(...)
1121           This is a very special aio request: Instead of doing something, it
1122           is a container for other aio requests, which is useful if you want
1123           to bundle many requests into a single, composite, request with a
1124           definite callback and the ability to cancel the whole request with
1125           its subrequests.
1126
1127           Returns an object of class IO::AIO::GRP. See its documentation
1128           below for more info.
1129
1130           Example:
1131
1132              my $grp = aio_group sub {
1133                 print "all stats done\n";
1134              };
1135
1136              add $grp
1137                 (aio_stat ...),
1138                 (aio_stat ...),
1139                 ...;
1140
1141       aio_nop $callback->()
1142           This is a special request - it does nothing in itself and is only
1143           used for side effects, such as when you want to add a dummy request
1144           to a group so that finishing the requests in the group depends on
1145           executing the given code.
1146
1147           While this request does nothing, it still goes through the
1148           execution phase and still requires a worker thread. Thus, the
1149           callback will not be executed immediately but only after other
1150           requests in the queue have entered their execution phase. This can
1151           be used to measure request latency.
1152
1153       IO::AIO::aio_busy $fractional_seconds, $callback->()  *NOT EXPORTED*
1154           Mainly used for debugging and benchmarking, this aio request puts
1155           one of the request workers to sleep for the given time.
1156
1157           While it is theoretically handy to have simple I/O scheduling
1158           requests like sleep and file handle readable/writable, the overhead
1159           this creates is immense (it blocks a thread for a long time) so do
1160           not use this function except to put your application under
1161           artificial I/O pressure.
1162
1163   IO::AIO::WD - multiple working directories
1164       Your process only has one current working directory, which is used by
1165       all threads. This makes it hard to use relative paths (some other
1166       component could call "chdir" at any time, and it is hard to control
1167       when the path will be used by IO::AIO).
1168
1169       One solution for this is to always use absolute paths. This usually
1170       works, but can be quite slow (the kernel has to walk the whole path on
1171       every access), and can also be a hassle to implement.
1172
1173       Newer POSIX systems have a number of functions (openat, fdopendir,
1174       futimensat and so on) that make it possible to specify working
1175       directories per operation.
1176
1177       For portability, and because the clowns who "designed", or shall I
1178       write, perpetrated this new interface were obviously half-drunk, this
1179       abstraction cannot be perfect, though.
1180
1181       IO::AIO allows you to convert directory paths into a so-called
1182       IO::AIO::WD object. This object stores the canonicalised, absolute
1183       version of the path, and on systems that allow it, also a directory
1184       file descriptor.
1185
1186       Everywhere where a pathname is accepted by IO::AIO (e.g. in "aio_stat"
1187       or "aio_unlink"), one can specify an array reference with an
1188       IO::AIO::WD object and a pathname instead (or the IO::AIO::WD object
1189       alone, which gets interpreted as "[$wd, "."]"). If the pathname is
1190       absolute, the IO::AIO::WD object is ignored, otherwise the pathname is
1191       resolved relative to that IO::AIO::WD object.
1192
1193       For example, to get a wd object for /etc and then stat passwd inside,
1194       you would write:
1195
1196          aio_wd "/etc", sub {
1197             my $etcdir = shift;
1198
1199             # although $etcdir can be undef on error, there is generally no reason
1200             # to check for errors here, as aio_stat will fail with ENOENT
1201             # when $etcdir is undef.
1202
1203             aio_stat [$etcdir, "passwd"], sub {
1204                # yay
1205             };
1206          };
1207
1208       The fact that "aio_wd" is a request and not a normal function shows
1209       that creating an IO::AIO::WD object is itself a potentially blocking
1210       operation, which is why it is done asynchronously.
1211
1212       To stat the directory obtained with "aio_wd" above, one could write
1213       either of the following three request calls:
1214
1215          aio_lstat "/etc"    , sub { ...  # pathname as normal string
1216          aio_lstat [$wd, "."], sub { ...  # "." relative to $wd (i.e. $wd itself)
1217          aio_lstat $wd       , sub { ...  # shorthand for the previous
1218
1219       As with normal pathnames, IO::AIO keeps a copy of the working directory
1220       object and the pathname string, so you could write the following
1221       without causing any issues due to $path getting reused:
1222
1223          my $path = [$wd, undef];
1224
1225          for my $name (qw(abc def ghi)) {
1226             $path->[1] = $name;
1227             aio_stat $path, sub {
1228                # ...
1229             };
1230          }
1231
1232       There are some caveats: when directories get renamed (or deleted), the
1233       pathname string doesn't change, so will point to the new directory (or
1234       nowhere at all), while the directory fd, if available on the system,
1235       will still point to the original directory. Most functions accepting a
1236       pathname will use the directory fd on newer systems, and the string on
1237       older systems. Some functions (such as "aio_realpath") will always rely
1238       on the string form of the pathname.
1239
1240       So this functionality is mainly useful to get some protection against
1241       "chdir", to easily get an absolute path out of a relative path for
1242       future reference, and to speed up doing many operations in the same
1243       directory (e.g. when stat'ing all files in a directory).
1244
1245       The following functions implement this working directory abstraction:
1246
1247       aio_wd $pathname, $callback->($wd)
1248           Asynchonously canonicalise the given pathname and convert it to an
1249           IO::AIO::WD object representing it. If possible and supported on
1250           the system, also open a directory fd to speed up pathname
1251           resolution relative to this working directory.
1252
1253           If something goes wrong, then "undef" is passwd to the callback
1254           instead of a working directory object and $! is set appropriately.
1255           Since passing "undef" as working directory component of a pathname
1256           fails the request with "ENOENT", there is often no need for error
1257           checking in the "aio_wd" callback, as future requests using the
1258           value will fail in the expected way.
1259
1260       IO::AIO::CWD
1261           This is a compile time constant (object) that represents the
1262           process current working directory.
1263
1264           Specifying this object as working directory object for a pathname
1265           is as if the pathname would be specified directly, without a
1266           directory object. For example, these calls are functionally
1267           identical:
1268
1269              aio_stat "somefile", sub { ... };
1270              aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1271
1272       To recover the path associated with an IO::AIO::WD object, you can use
1273       "aio_realpath":
1274
1275          aio_realpath $wd, sub {
1276             warn "path is $_[0]\n";
1277          };
1278
1279       Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir"
1280       sometimes, fall back to using an absolue path.
1281
1282   IO::AIO::REQ CLASS
1283       All non-aggregate "aio_*" functions return an object of this class when
1284       called in non-void context.
1285
1286       cancel $req
1287           Cancels the request, if possible. Has the effect of skipping
1288           execution when entering the execute state and skipping calling the
1289           callback when entering the the result state, but will leave the
1290           request otherwise untouched (with the exception of readdir). That
1291           means that requests that currently execute will not be stopped and
1292           resources held by the request will not be freed prematurely.
1293
1294       cb $req $callback->(...)
1295           Replace (or simply set) the callback registered to the request.
1296
1297   IO::AIO::GRP CLASS
1298       This class is a subclass of IO::AIO::REQ, so all its methods apply to
1299       objects of this class, too.
1300
1301       A IO::AIO::GRP object is a special request that can contain multiple
1302       other aio requests.
1303
1304       You create one by calling the "aio_group" constructing function with a
1305       callback that will be called when all contained requests have entered
1306       the "done" state:
1307
1308          my $grp = aio_group sub {
1309             print "all requests are done\n";
1310          };
1311
1312       You add requests by calling the "add" method with one or more
1313       "IO::AIO::REQ" objects:
1314
1315          $grp->add (aio_unlink "...");
1316
1317          add $grp aio_stat "...", sub {
1318             $_[0] or return $grp->result ("error");
1319
1320             # add another request dynamically, if first succeeded
1321             add $grp aio_open "...", sub {
1322                $grp->result ("ok");
1323             };
1324          };
1325
1326       This makes it very easy to create composite requests (see the source of
1327       "aio_move" for an application) that work and feel like simple requests.
1328
1329       •   The IO::AIO::GRP objects will be cleaned up during calls to
1330           "IO::AIO::poll_cb", just like any other request.
1331
1332       •   They can be canceled like any other request. Canceling will cancel
1333           not only the request itself, but also all requests it contains.
1334
1335       •   They can also can also be added to other IO::AIO::GRP objects.
1336
1337       •   You must not add requests to a group from within the group callback
1338           (or any later time).
1339
1340       Their lifetime, simplified, looks like this: when they are empty, they
1341       will finish very quickly. If they contain only requests that are in the
1342       "done" state, they will also finish. Otherwise they will continue to
1343       exist.
1344
1345       That means after creating a group you have some time to add requests
1346       (precisely before the callback has been invoked, which is only done
1347       within the "poll_cb"). And in the callbacks of those requests, you can
1348       add further requests to the group. And only when all those requests
1349       have finished will the the group itself finish.
1350
1351       add $grp ...
1352       $grp->add (...)
1353           Add one or more requests to the group. Any type of IO::AIO::REQ can
1354           be added, including other groups, as long as you do not create
1355           circular dependencies.
1356
1357           Returns all its arguments.
1358
1359       $grp->cancel_subs
1360           Cancel all subrequests and clears any feeder, but not the group
1361           request itself. Useful when you queued a lot of events but got a
1362           result early.
1363
1364           The group request will finish normally (you cannot add requests to
1365           the group).
1366
1367       $grp->result (...)
1368           Set the result value(s) that will be passed to the group callback
1369           when all subrequests have finished and set the groups errno to the
1370           current value of errno (just like calling "errno" without an error
1371           number). By default, no argument will be passed and errno is zero.
1372
1373       $grp->errno ([$errno])
1374           Sets the group errno value to $errno, or the current value of errno
1375           when the argument is missing.
1376
1377           Every aio request has an associated errno value that is restored
1378           when the callback is invoked. This method lets you change this
1379           value from its default (0).
1380
1381           Calling "result" will also set errno, so make sure you either set
1382           $!  before the call to "result", or call c<errno> after it.
1383
1384       feed $grp $callback->($grp)
1385           Sets a feeder/generator on this group: every group can have an
1386           attached generator that generates requests if idle. The idea behind
1387           this is that, although you could just queue as many requests as you
1388           want in a group, this might starve other requests for a potentially
1389           long time. For example, "aio_scandir" might generate hundreds of
1390           thousands of "aio_stat" requests, delaying any later requests for a
1391           long time.
1392
1393           To avoid this, and allow incremental generation of requests, you
1394           can instead a group and set a feeder on it that generates those
1395           requests. The feed callback will be called whenever there are few
1396           enough (see "limit", below) requests active in the group itself and
1397           is expected to queue more requests.
1398
1399           The feed callback can queue as many requests as it likes (i.e.
1400           "add" does not impose any limits).
1401
1402           If the feed does not queue more requests when called, it will be
1403           automatically removed from the group.
1404
1405           If the feed limit is 0 when this method is called, it will be set
1406           to 2 automatically.
1407
1408           Example:
1409
1410              # stat all files in @files, but only ever use four aio requests concurrently:
1411
1412              my $grp = aio_group sub { print "finished\n" };
1413              limit $grp 4;
1414              feed $grp sub {
1415                 my $file = pop @files
1416                    or return;
1417
1418                 add $grp aio_stat $file, sub { ... };
1419              };
1420
1421       limit $grp $num
1422           Sets the feeder limit for the group: The feeder will be called
1423           whenever the group contains less than this many requests.
1424
1425           Setting the limit to 0 will pause the feeding process.
1426
1427           The default value for the limit is 0, but note that setting a
1428           feeder automatically bumps it up to 2.
1429
1430   SUPPORT FUNCTIONS
1431       EVENT PROCESSING AND EVENT LOOP INTEGRATION
1432
1433       $fileno = IO::AIO::poll_fileno
1434           Return the request result pipe file descriptor. This filehandle
1435           must be polled for reading by some mechanism outside this module
1436           (e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If
1437           the pipe becomes readable you have to call "poll_cb" to check the
1438           results.
1439
1440           See "poll_cb" for an example.
1441
1442       IO::AIO::poll_cb
1443           Process some requests that have reached the result phase (i.e. they
1444           have been executed but the results are not yet reported). You have
1445           to call this "regularly" to finish outstanding requests.
1446
1447           Returns 0 if all events could be processed (or there were no events
1448           to process), or "-1" if it returned earlier for whatever reason.
1449           Returns immediately when no events are outstanding. The amount of
1450           events processed depends on the settings of
1451           "IO::AIO::max_poll_req", "IO::AIO::max_poll_time" and
1452           "IO::AIO::max_outstanding".
1453
1454           If not all requests were processed for whatever reason, the poll
1455           file descriptor will still be ready when "poll_cb" returns, so
1456           normally you don't have to do anything special to have it called
1457           later.
1458
1459           Apart from calling "IO::AIO::poll_cb" when the event filehandle
1460           becomes ready, it can be beneficial to call this function from
1461           loops which submit a lot of requests, to make sure the results get
1462           processed when they become available and not just when the loop is
1463           finished and the event loop takes over again. This function returns
1464           very fast when there are no outstanding requests.
1465
1466           Example: Install an Event watcher that automatically calls
1467           IO::AIO::poll_cb with high priority (more examples can be found in
1468           the SYNOPSIS section, at the top of this document):
1469
1470              Event->io (fd => IO::AIO::poll_fileno,
1471                         poll => 'r', async => 1,
1472                         cb => \&IO::AIO::poll_cb);
1473
1474       IO::AIO::poll_wait
1475           Wait until either at least one request is in the result phase or no
1476           requests are outstanding anymore.
1477
1478           This is useful if you want to synchronously wait for some requests
1479           to become ready, without actually handling them.
1480
1481           See "nreqs" for an example.
1482
1483       IO::AIO::poll
1484           Waits until some requests have been handled.
1485
1486           Returns the number of requests processed, but is otherwise strictly
1487           equivalent to:
1488
1489              IO::AIO::poll_wait, IO::AIO::poll_cb
1490
1491       IO::AIO::flush
1492           Wait till all outstanding AIO requests have been handled.
1493
1494           Strictly equivalent to:
1495
1496              IO::AIO::poll_wait, IO::AIO::poll_cb
1497                 while IO::AIO::nreqs;
1498
1499           This function can be useful at program aborts, to make sure
1500           outstanding I/O has been done ("IO::AIO" uses an "END" block which
1501           already calls this function on normal exits), or when you are
1502           merely using "IO::AIO" for its more advanced functions, rather than
1503           for async I/O, e.g.:
1504
1505              my ($dirs, $nondirs);
1506              IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1507              IO::AIO::flush;
1508              # $dirs, $nondirs are now set
1509
1510       IO::AIO::max_poll_reqs $nreqs
1511       IO::AIO::max_poll_time $seconds
1512           These set the maximum number of requests (default 0, meaning
1513           infinity) that are being processed by "IO::AIO::poll_cb" in one
1514           call, respectively the maximum amount of time (default 0, meaning
1515           infinity) spent in "IO::AIO::poll_cb" to process requests (more
1516           correctly the mininum amount of time "poll_cb" is allowed to use).
1517
1518           Setting "max_poll_time" to a non-zero value creates an overhead of
1519           one syscall per request processed, which is not normally a problem
1520           unless your callbacks are really really fast or your OS is really
1521           really slow (I am not mentioning Solaris here). Using
1522           "max_poll_reqs" incurs no overhead.
1523
1524           Setting these is useful if you want to ensure some level of
1525           interactiveness when perl is not fast enough to process all
1526           requests in time.
1527
1528           For interactive programs, values such as 0.01 to 0.1 should be
1529           fine.
1530
1531           Example: Install an Event watcher that automatically calls
1532           IO::AIO::poll_cb with low priority, to ensure that other parts of
1533           the program get the CPU sometimes even under high AIO load.
1534
1535              # try not to spend much more than 0.1s in poll_cb
1536              IO::AIO::max_poll_time 0.1;
1537
1538              # use a low priority so other tasks have priority
1539              Event->io (fd => IO::AIO::poll_fileno,
1540                         poll => 'r', nice => 1,
1541                         cb => &IO::AIO::poll_cb);
1542
1543       CONTROLLING THE NUMBER OF THREADS
1544
1545       IO::AIO::min_parallel $nthreads
1546           Set the minimum number of AIO threads to $nthreads. The current
1547           default is 8, which means eight asynchronous operations can execute
1548           concurrently at any one time (the number of outstanding requests,
1549           however, is unlimited).
1550
1551           IO::AIO starts threads only on demand, when an AIO request is
1552           queued and no free thread exists. Please note that queueing up a
1553           hundred requests can create demand for a hundred threads, even if
1554           it turns out that everything is in the cache and could have been
1555           processed faster by a single thread.
1556
1557           It is recommended to keep the number of threads relatively low, as
1558           some Linux kernel versions will scale negatively with the number of
1559           threads (higher parallelity => MUCH higher latency). With current
1560           Linux 2.6 versions, 4-32 threads should be fine.
1561
1562           Under most circumstances you don't need to call this function, as
1563           the module selects a default that is suitable for low to moderate
1564           load.
1565
1566       IO::AIO::max_parallel $nthreads
1567           Sets the maximum number of AIO threads to $nthreads. If more than
1568           the specified number of threads are currently running, this
1569           function kills them. This function blocks until the limit is
1570           reached.
1571
1572           While $nthreads are zero, aio requests get queued but not executed
1573           until the number of threads has been increased again.
1574
1575           This module automatically runs "max_parallel 0" at program end, to
1576           ensure that all threads are killed and that there are no
1577           outstanding requests.
1578
1579           Under normal circumstances you don't need to call this function.
1580
1581       IO::AIO::max_idle $nthreads
1582           Limit the number of threads (default: 4) that are allowed to idle
1583           (i.e., threads that did not get a request to process within the
1584           idle timeout (default: 10 seconds). That means if a thread becomes
1585           idle while $nthreads other threads are also idle, it will free its
1586           resources and exit.
1587
1588           This is useful when you allow a large number of threads (e.g. 100
1589           or 1000) to allow for extremely high load situations, but want to
1590           free resources under normal circumstances (1000 threads can easily
1591           consume 30MB of RAM).
1592
1593           The default is probably ok in most situations, especially if thread
1594           creation is fast. If thread creation is very slow on your system
1595           you might want to use larger values.
1596
1597       IO::AIO::idle_timeout $seconds
1598           Sets the minimum idle timeout (default 10) after which worker
1599           threads are allowed to exit. SEe "IO::AIO::max_idle".
1600
1601       IO::AIO::max_outstanding $maxreqs
1602           Sets the maximum number of outstanding requests to $nreqs. If you
1603           do queue up more than this number of requests, the next call to
1604           "IO::AIO::poll_cb" (and other functions calling "poll_cb", such as
1605           "IO::AIO::flush" or "IO::AIO::poll") will block until the limit is
1606           no longer exceeded.
1607
1608           In other words, this setting does not enforce a queue limit, but
1609           can be used to make poll functions block if the limit is exceeded.
1610
1611           This is a very bad function to use in interactive programs because
1612           it blocks, and a bad way to reduce concurrency because it is
1613           inexact: Better use an "aio_group" together with a feed callback.
1614
1615           Its main use is in scripts without an event loop - when you want to
1616           stat a lot of files, you can write something like this:
1617
1618              IO::AIO::max_outstanding 32;
1619
1620              for my $path (...) {
1621                 aio_stat $path , ...;
1622                 IO::AIO::poll_cb;
1623              }
1624
1625              IO::AIO::flush;
1626
1627           The call to "poll_cb" inside the loop will normally return
1628           instantly, but as soon as more thna 32 reqeusts are in-flight, it
1629           will block until some requests have been handled. This keeps the
1630           loop from pushing a large number of "aio_stat" requests onto the
1631           queue.
1632
1633           The default value for "max_outstanding" is very large, so there is
1634           no practical limit on the number of outstanding requests.
1635
1636       STATISTICAL INFORMATION
1637
1638       IO::AIO::nreqs
1639           Returns the number of requests currently in the ready, execute or
1640           pending states (i.e. for which their callback has not been invoked
1641           yet).
1642
1643           Example: wait till there are no outstanding requests anymore:
1644
1645              IO::AIO::poll_wait, IO::AIO::poll_cb
1646                 while IO::AIO::nreqs;
1647
1648       IO::AIO::nready
1649           Returns the number of requests currently in the ready state (not
1650           yet executed).
1651
1652       IO::AIO::npending
1653           Returns the number of requests currently in the pending state
1654           (executed, but not yet processed by poll_cb).
1655
1656       SUBSECOND STAT TIME ACCESS
1657
1658       Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
1659       generally find access/modification and change times with subsecond time
1660       accuracy of the system supports it, but perl's built-in functions only
1661       return the integer part.
1662
1663       The following functions return the timestamps of the most recent stat
1664       with subsecond precision on most systems and work both after
1665       "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
1666       value is only meaningful after a successful "stat"/"lstat" call, or
1667       during/after a successful "aio_stat"/"aio_lstat" callback.
1668
1669       This is similar to the Time::HiRes "stat" functions, but can return
1670       full resolution without rounding and work with standard perl "stat",
1671       alleviating the need to call the special "Time::HiRes" functions, which
1672       do not act like their perl counterparts.
1673
1674       On operating systems or file systems where subsecond time resolution is
1675       not supported or could not be detected, a fractional part of 0 is
1676       returned, so it is always safe to call these functions.
1677
1678       $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
1679       IO::AIO::st_btime
1680           Return the access, modication, change or birth time, respectively,
1681           including fractional part. Due to the limited precision of floating
1682           point, the accuracy on most platforms is only a bit better than
1683           milliseconds for times around now - see the nsec function family,
1684           below, for full accuracy.
1685
1686           File birth time is only available when the OS and perl support it
1687           (on FreeBSD and NetBSD at the time of this writing, although
1688           support is adaptive, so if your OS/perl gains support, IO::AIO can
1689           take advantage of it). On systems where it isn't available, 0 is
1690           currently returned, but this might change to "undef" in a future
1691           version.
1692
1693       ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1694           Returns access, modification, change and birth time all in one go,
1695           and maybe more times in the future version.
1696
1697       $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
1698       IO::AIO::st_ctimensec, IO::AIO::st_btimensec
1699           Return the fractional access, modifcation, change or birth time, in
1700           nanoseconds, as an integer in the range 0 to 999999999.
1701
1702           Note that no accessors are provided for access, modification and
1703           change times - you need to get those from "stat _" if required
1704           ("int IO::AIO::st_atime" and so on will not generally give you the
1705           correct value).
1706
1707       $seconds = IO::AIO::st_btimesec
1708           The (integral) seconds part of the file birth time, if available.
1709
1710       ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1711           Like the functions above, but returns all four times in one go (and
1712           maybe more in future versions).
1713
1714       $counter = IO::AIO::st_gen
1715           Returns the generation counter (in practice this is just a random
1716           number) of the file. This is only available on platforms which have
1717           this member in their "struct stat" (most BSDs at the time of this
1718           writing) and generally only to the root usert. If unsupported, 0 is
1719           returned, but this might change to "undef" in a future version.
1720
1721       Example: print the high resolution modification time of /etc, using
1722       "stat", and "IO::AIO::aio_stat".
1723
1724          if (stat "/etc") {
1725             printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
1726          }
1727
1728          IO::AIO::aio_stat "/etc", sub {
1729             $_[0]
1730                and return;
1731
1732             printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
1733          };
1734
1735          IO::AIO::flush;
1736
1737       Output of the awbove on my system, showing reduced and full accuracy:
1738
1739          stat(/etc) mtime: 1534043702.020808
1740          aio_stat(/etc) mtime: 1534043702.020807792
1741
1742       MISCELLANEOUS FUNCTIONS
1743
1744       IO::AIO implements some functions that are useful when you want to use
1745       some "Advanced I/O" function not available to in Perl, without going
1746       the "Asynchronous I/O" route. Many of these have an asynchronous
1747       "aio_*" counterpart.
1748
1749       $numfd = IO::AIO::get_fdlimit
1750           Tries to find the current file descriptor limit and returns it, or
1751           "undef" and sets $! in case of an error. The limit is one larger
1752           than the highest valid file descriptor number.
1753
1754       IO::AIO::min_fdlimit [$numfd]
1755           Try to increase the current file descriptor limit(s) to at least
1756           $numfd by changing the soft or hard file descriptor resource limit.
1757           If $numfd is missing, it will try to set a very high limit,
1758           although this is not recommended when you know the actual minimum
1759           that you require.
1760
1761           If the limit cannot be raised enough, the function makes a best-
1762           effort attempt to increase the limit as much as possible, using
1763           various tricks, while still failing. You can query the resulting
1764           limit using "IO::AIO::get_fdlimit".
1765
1766           If an error occurs, returns "undef" and sets $!, otherwise returns
1767           true.
1768
1769       IO::AIO::sendfile $ofh, $ifh, $offset, $count
1770           Calls the "eio_sendfile_sync" function, which is like
1771           "aio_sendfile", but is blocking (this makes most sense if you know
1772           the input data is likely cached already and the output filehandle
1773           is set to non-blocking operations).
1774
1775           Returns the number of bytes copied, or "-1" on error.
1776
1777       IO::AIO::fadvise $fh, $offset, $len, $advice
1778           Simply calls the "posix_fadvise" function (see its manpage for
1779           details). The following advice constants are available:
1780           "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1781           "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1782           "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1783
1784           On systems that do not implement "posix_fadvise", this function
1785           returns ENOSYS, otherwise the return value of "posix_fadvise".
1786
1787       IO::AIO::madvise $scalar, $offset, $len, $advice
1788           Simply calls the "posix_madvise" function (see its manpage for
1789           details). The following advice constants are available:
1790           "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1791           "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1792           "IO::AIO::MADV_DONTNEED".
1793
1794           If $offset is negative, counts from the end. If $length is
1795           negative, the remaining length of the $scalar is used. If possible,
1796           $length will be reduced to fit into the $scalar.
1797
1798           On systems that do not implement "posix_madvise", this function
1799           returns ENOSYS, otherwise the return value of "posix_madvise".
1800
1801       IO::AIO::mprotect $scalar, $offset, $len, $protect
1802           Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1803           $scalar (see its manpage for details). The following protect
1804           constants are available: "IO::AIO::PROT_NONE",
1805           "IO::AIO::PROT_READ", "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1806
1807           If $offset is negative, counts from the end. If $length is
1808           negative, the remaining length of the $scalar is used. If possible,
1809           $length will be reduced to fit into the $scalar.
1810
1811           On systems that do not implement "mprotect", this function returns
1812           ENOSYS, otherwise the return value of "mprotect".
1813
1814       IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1815           Memory-maps a file (or anonymous memory range) and attaches it to
1816           the given $scalar, which will act like a string scalar. Returns
1817           true on success, and false otherwise.
1818
1819           The scalar must exist, but its contents do not matter - this means
1820           you cannot use a nonexistant array or hash element. When in doubt,
1821           "undef" the scalar first.
1822
1823           The only operations allowed on the mmapped scalar are
1824           "substr"/"vec", which don't change the string length, and most
1825           read-only operations such as copying it or searching it with
1826           regexes and so on.
1827
1828           Anything else is unsafe and will, at best, result in memory leaks.
1829
1830           The memory map associated with the $scalar is automatically removed
1831           when the $scalar is undef'd or destroyed, or when the
1832           "IO::AIO::mmap" or "IO::AIO::munmap" functions are called on it.
1833
1834           This calls the "mmap"(2) function internally. See your system's
1835           manual page for details on the $length, $prot and $flags
1836           parameters.
1837
1838           The $length must be larger than zero and smaller than the actual
1839           filesize.
1840
1841           $prot is a combination of "IO::AIO::PROT_NONE",
1842           "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1843           "IO::AIO::PROT_WRITE",
1844
1845           $flags can be a combination of "IO::AIO::MAP_SHARED" or
1846           "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1847           not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set
1848           to "MAP_ANON" if your system only provides this constant),
1849           "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1850           "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1851           "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1852           "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1853           "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1854           "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1855
1856           If $fh is "undef", then a file descriptor of "-1" is passed.
1857
1858           $offset is the offset from the start of the file - it generally
1859           must be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
1860
1861           Example:
1862
1863              use Digest::MD5;
1864              use IO::AIO;
1865
1866              open my $fh, "<verybigfile"
1867                 or die "$!";
1868
1869              IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
1870                 or die "verybigfile: $!";
1871
1872              my $fast_md5 = md5 $data;
1873
1874       IO::AIO::munmap $scalar
1875           Removes a previous mmap and undefines the $scalar.
1876
1877       IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
1878       $new_address = 0]
1879           Calls the Linux-specific mremap(2) system call. The $scalar must
1880           have been mapped by "IO::AIO::mmap", and $flags must currently
1881           either be 0 or "IO::AIO::MREMAP_MAYMOVE".
1882
1883           Returns true if successful, and false otherwise. If the underlying
1884           mmapped region has changed address, then the true value has the
1885           numerical value 1, otherwise it has the numerical value 0:
1886
1887              my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
1888                 or die "mremap: $!";
1889
1890              if ($success*1) {
1891                 warn "scalar has chanegd address in memory\n";
1892              }
1893
1894           "IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
1895           implemented, but not supported and might go away in a future
1896           version.
1897
1898           On systems where this call is not supported or is not emulated,
1899           this call returns falls and sets $! to "ENOSYS".
1900
1901       IO::AIO::mlockall $flags
1902           Calls the "eio_mlockall_sync" function, which is like
1903           "aio_mlockall", but is blocking.
1904
1905       IO::AIO::munlock $scalar, $offset = 0, $length = undef
1906           Calls the "munlock" function, undoing the effects of a previous
1907           "aio_mlock" call (see its description for details).
1908
1909       IO::AIO::munlockall
1910           Calls the "munlockall" function.
1911
1912           On systems that do not implement "munlockall", this function
1913           returns ENOSYS, otherwise the return value of "munlockall".
1914
1915       $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1916           Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1917           socket and return the new file handle on success, or sets $! and
1918           returns "undef" on error.
1919
1920           The remote name of the new socket will be stored in $sockaddr,
1921           which will be extended to allow for at least $sockaddr_maxlen
1922           octets. If the socket name does not fit into $sockaddr_maxlen
1923           octets, this is signaled by returning a longer string in $sockaddr,
1924           which might or might not be truncated.
1925
1926           To accept name-less sockets, use "undef" for $sockaddr and 0 for
1927           $sockaddr_maxlen.
1928
1929           The main reasons to use this syscall rather than portable accept(2)
1930           are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC"
1931           flags and you can accept name-less sockets by specifying 0 for
1932           $sockaddr_maxlen, which is sadly not possible with perl's interface
1933           to "accept".
1934
1935       IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1936           Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
1937           $w_off are "undef", then "NULL" is passed for these, otherwise they
1938           should be the file offset.
1939
1940           $r_fh and $w_fh should not refer to the same file, as splice might
1941           silently corrupt the data in this case.
1942
1943           The following symbol flag values are available:
1944           "IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
1945           "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
1946
1947           See the splice(2) manpage for details.
1948
1949       IO::AIO::tee $r_fh, $w_fh, $length, $flags
1950           Calls the GNU/Linux tee(2) syscall, see its manpage and the
1951           description for "IO::AIO::splice" above for details.
1952
1953       $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
1954           Attempts to query or change the pipe buffer size. Obviously works
1955           only on pipes, and currently works only on GNU/Linux systems, and
1956           fails with "-1"/"ENOSYS" everywhere else. If anybody knows how to
1957           influence pipe buffer size on other systems, drop me a note.
1958
1959       ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
1960           This is a direct interface to the Linux pipe2(2) system call. If
1961           $flags is missing or 0, then this should be the same as a call to
1962           perl's built-in "pipe" function and create a new pipe, and works on
1963           systems that lack the pipe2 syscall. On win32, this case invokes
1964           "_pipe (..., 4096, O_BINARY)".
1965
1966           If $flags is non-zero, it tries to invoke the pipe2 system call
1967           with the given flags (Linux 2.6.27, glibc 2.9).
1968
1969           On success, the read and write file handles are returned.
1970
1971           On error, nothing will be returned. If the pipe2 syscall is missing
1972           and $flags is non-zero, fails with "ENOSYS".
1973
1974           Please refer to pipe2(2) for more info on the $flags, but at the
1975           time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK"
1976           and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were
1977           supported.
1978
1979           Example: create a pipe race-free w.r.t. threads and fork:
1980
1981              my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1982                 or die "pipe2: $!\n";
1983
1984       $fh = IO::AIO::memfd_create $pathname[, $flags]
1985           This is a direct interface to the Linux memfd_create(2) system
1986           call. The (unhelpful) default for $flags is 0, but your default
1987           should be "IO::AIO::MFD_CLOEXEC".
1988
1989           On success, the new memfd filehandle is returned, otherwise returns
1990           "undef". If the memfd_create syscall is missing, fails with
1991           "ENOSYS".
1992
1993           Please refer to memfd_create(2) for more info on this call.
1994
1995           The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
1996           "IO::AIO::MFD_ALLOW_SEALING" and "IO::AIO::MFD_HUGETLB".
1997
1998           Example: create a new memfd.
1999
2000              my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2001                 or die "memfd_create: $!\n";
2002
2003       $fh = IO::AIO::pidfd_open $pid[, $flags]
2004           This is an interface to the Linux pidfd_open(2) system call. The
2005           default for $flags is 0.
2006
2007           On success, a new pidfd filehandle is returned (that is already set
2008           to close-on-exec), otherwise returns "undef". If the syscall is
2009           missing, fails with "ENOSYS".
2010
2011           Example: open pid 6341 as pidfd.
2012
2013              my $fh = IO::AIO::pidfd_open 6341
2014                 or die "pidfd_open: $!\n";
2015
2016       $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
2017       $flags]]
2018           This is an interface to the Linux pidfd_send_signal system call.
2019           The default for $siginfo is "undef" and the default for $flags is
2020           0.
2021
2022           Returns the system call status.  If the syscall is missing, fails
2023           with "ENOSYS".
2024
2025           When specified, $siginfo must be a reference to a hash with one or
2026           more of the following members:
2027
2028           code - the "si_code" member
2029           pid - the "si_pid" member
2030           uid - the "si_uid" member
2031           value_int - the "si_value.sival_int" member
2032           value_ptr - the "si_value.sival_ptr" member, specified as an
2033           integer
2034
2035           Example: send a SIGKILL to the specified process.
2036
2037              my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2038                 and die "pidfd_send_signal: $!\n";
2039
2040           Example: send a SIGKILL to the specified process with extra data.
2041
2042              my $status = IO::AIO::pidfd_send_signal $pidfh, 9,  { code => -1, value_int => 7 }
2043                 and die "pidfd_send_signal: $!\n";
2044
2045       $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2046           This is an interface to the Linux pidfd_getfd system call. The
2047           default for $flags is 0.
2048
2049           On success, returns a dup'ed copy of the target file descriptor
2050           (specified as an integer) returned (that is already set to close-
2051           on-exec), otherwise returns "undef". If the syscall is missing,
2052           fails with "ENOSYS".
2053
2054           Example: get a copy of standard error of another process and print
2055           soemthing to it.
2056
2057              my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2058                 or die "pidfd_getfd: $!\n";
2059              print $errfh "stderr\n";
2060
2061       $fh = IO::AIO::eventfd [$initval, [$flags]]
2062           This is a direct interface to the Linux eventfd(2) system call. The
2063           (unhelpful) defaults for $initval and $flags are 0 for both.
2064
2065           On success, the new eventfd filehandle is returned, otherwise
2066           returns "undef". If the eventfd syscall is missing, fails with
2067           "ENOSYS".
2068
2069           Please refer to eventfd(2) for more info on this call.
2070
2071           The following symbol flag values are available:
2072           "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
2073           "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
2074
2075           Example: create a new eventfd filehandle:
2076
2077              $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
2078                 or die "eventfd: $!\n";
2079
2080       $fh = IO::AIO::timerfd_create $clockid[, $flags]
2081           This is a direct interface to the Linux timerfd_create(2) system
2082           call. The (unhelpful) default for $flags is 0, but your default
2083           should be "IO::AIO::TFD_CLOEXEC".
2084
2085           On success, the new timerfd filehandle is returned, otherwise
2086           returns "undef". If the timerfd_create syscall is missing, fails
2087           with "ENOSYS".
2088
2089           Please refer to timerfd_create(2) for more info on this call.
2090
2091           The following $clockid values are available:
2092           "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
2093           "IO::AIO::CLOCK_CLOCK_BOOTTIME" (Linux 3.15)
2094           "IO::AIO::CLOCK_CLOCK_REALTIME_ALARM" (Linux 3.11) and
2095           "IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM" (Linux 3.11).
2096
2097           The following $flags values are available (Linux 2.6.27):
2098           "IO::AIO::TFD_NONBLOCK" and "IO::AIO::TFD_CLOEXEC".
2099
2100           Example: create a new timerfd and set it to one-second repeated
2101           alarms, then wait for two alarms:
2102
2103              my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
2104                 or die "timerfd_create: $!\n";
2105
2106              defined IO::AIO::timerfd_settime $fh, 0, 1, 1
2107                 or die "timerfd_settime: $!\n";
2108
2109              for (1..2) {
2110                 8 == sysread $fh, my $buf, 8
2111                    or die "timerfd read failure\n";
2112
2113                 printf "number of expirations (likely 1): %d\n",
2114                    unpack "Q", $buf;
2115              }
2116
2117       ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags,
2118       $new_interval, $nbw_value
2119           This is a direct interface to the Linux timerfd_settime(2) system
2120           call. Please refer to its manpage for more info on this call.
2121
2122           The new itimerspec is specified using two (possibly fractional)
2123           second values, $new_interval and $new_value).
2124
2125           On success, the current interval and value are returned (as per
2126           "timerfd_gettime"). On failure, the empty list is returned.
2127
2128           The following $flags values are available:
2129           "IO::AIO::TFD_TIMER_ABSTIME" and
2130           "IO::AIO::TFD_TIMER_CANCEL_ON_SET".
2131
2132           See "IO::AIO::timerfd_create" for a full example.
2133
2134       ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
2135           This is a direct interface to the Linux timerfd_gettime(2) system
2136           call. Please refer to its manpage for more info on this call.
2137
2138           On success, returns the current values of interval and value for
2139           the given timerfd (as potentially fractional second values). On
2140           failure, the empty list is returned.
2141

EVENT LOOP INTEGRATION

2143       It is recommended to use AnyEvent::AIO to integrate IO::AIO
2144       automatically into many event loops:
2145
2146        # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
2147        use AnyEvent::AIO;
2148
2149       You can also integrate IO::AIO manually into many event loops, here are
2150       some examples of how to do this:
2151
2152        # EV integration
2153        my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
2154
2155        # Event integration
2156        Event->io (fd => IO::AIO::poll_fileno,
2157                   poll => 'r',
2158                   cb => \&IO::AIO::poll_cb);
2159
2160        # Glib/Gtk2 integration
2161        add_watch Glib::IO IO::AIO::poll_fileno,
2162                  in => sub { IO::AIO::poll_cb; 1 };
2163
2164        # Tk integration
2165        Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
2166                                  readable => \&IO::AIO::poll_cb);
2167
2168        # Danga::Socket integration
2169        Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
2170                                    \&IO::AIO::poll_cb);
2171
2172   FORK BEHAVIOUR
2173       Usage of pthreads in a program changes the semantics of fork
2174       considerably. Specifically, only async-safe functions can be called
2175       after fork. Perl doesn't know about this, so in general, you cannot
2176       call fork with defined behaviour in perl if pthreads are involved.
2177       IO::AIO uses pthreads, so this applies, but many other extensions and
2178       (for inexplicable reasons) perl itself often is linked against
2179       pthreads, so this limitation applies to quite a lot of perls.
2180
2181       This module no longer tries to fight your OS, or POSIX. That means
2182       IO::AIO only works in the process that loaded it. Forking is fully
2183       supported, but using IO::AIO in the child is not.
2184
2185       You might get around by not using IO::AIO before (or after) forking.
2186       You could also try to call the IO::AIO::reinit function in the child:
2187
2188       IO::AIO::reinit
2189           Abandons all current requests and I/O threads and simply
2190           reinitialises all data structures. This is not an operation
2191           supported by any standards, but happens to work on GNU/Linux and
2192           some newer BSD systems.
2193
2194           The only reasonable use for this function is to call it after
2195           forking, if "IO::AIO" was used in the parent. Calling it while
2196           IO::AIO is active in the process will result in undefined
2197           behaviour. Calling it at any time will also result in any undefined
2198           (by POSIX) behaviour.
2199
2200   LINUX-SPECIFIC CALLS
2201       When a call is documented as "linux-specific" then this means it
2202       originated on GNU/Linux. "IO::AIO" will usually try to autodetect the
2203       availability and compatibility of such calls regardless of the platform
2204       it is compiled on, so platforms such as FreeBSD which often implement
2205       these calls will work. When in doubt, call them and see if they fail
2206       wth "ENOSYS".
2207
2208   MEMORY USAGE
2209       Per-request usage:
2210
2211       Each aio request uses - depending on your architecture - around 100-200
2212       bytes of memory. In addition, stat requests need a stat buffer
2213       (possibly a few hundred bytes), readdir requires a result buffer and so
2214       on. Perl scalars and other data passed into aio requests will also be
2215       locked and will consume memory till the request has entered the done
2216       state.
2217
2218       This is not awfully much, so queuing lots of requests is not usually a
2219       problem.
2220
2221       Per-thread usage:
2222
2223       In the execution phase, some aio requests require more memory for
2224       temporary buffers, and each thread requires a stack and other data
2225       structures (usually around 16k-128k, depending on the OS).
2226

KNOWN BUGS

2228       Known bugs will be fixed in the next release :)
2229

KNOWN ISSUES

2231       Calls that try to "import" foreign memory areas (such as
2232       "IO::AIO::mmap" or "IO::AIO::aio_slurp") do not work with generic
2233       lvalues, such as non-created hash slots or other scalars I didn't think
2234       of. It's best to avoid such and either use scalar variables or making
2235       sure that the scalar exists (e.g. by storing "undef") and isn't "funny"
2236       (e.g. tied).
2237
2238       I am not sure anything can be done about this, so this is considered a
2239       known issue, rather than a bug.
2240

SEE ALSO

2242       AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
2243       more natural syntax and IO::FDPass for file descriptor passing.
2244

AUTHOR

2246        Marc Lehmann <schmorp@schmorp.de>
2247        http://home.schmorp.de/
2248
2249
2250
2251perl v5.34.0                      2021-07-28                            AIO(3)
Impressum