1AIO(3) User Contributed Perl Documentation AIO(3)
2
6 IO::AIO - Asynchronous/Advanced Input/Output
7
9 use IO::AIO;
10 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
12 my $fh = shift
13 or die "/etc/passwd: $!";
14 ...
15 };
16 aio_unlink "/tmp/file", sub { };
18 aio_read $fh, 30000, 1024, $buffer, 0, sub {
20 $_[0] > 0 or die "read error: $!";
21 };
22 # version 2+ has request and group objects
24 use IO::AIO 2;
25 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 my $grp = aio_group sub { print "all stats done\n" };
31 add $grp aio_stat "..." for ...;
32
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 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 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 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 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 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 EXAMPLE
74 This is a simple example that uses the EV module and loads /etc/passwd
75 asynchronously:
76 use EV;
78 use IO::AIO;
79 # register the IO::AIO callback with EV
81 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
82 # 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 # stat'ing filehandles is generally non-blocking
89 my $size = -s $fh;
90 # 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 close $fh;
98 # file contents now in $contents
100 print $contents;
101 # exit event loop and program
103 EV::break;
104 };
105 };
106 # possibly queue up other requests, or open GUI windows,
108 # check for sockets etc. etc.
109 # process events as long as there are some:
111 EV::run;
112
114 Every "aio_*" function creates a request. which is a C data structure
115 not directly visible to Perl.
116 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 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 During their existance, aio requests travel through the following
126 states, in order:
127 ready
129 Immediately after a request is created it is put into the ready
130 state, waiting for a thread to execute it.
131 execute
133 A thread has accepted the request for processing and is currently
134 executing it (e.g. blocking in read).
135 pending
137 The request has been executed and is waiting for result processing.
138 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 result
144 The request results are processed synchronously by "poll_cb".
145 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 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
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 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 $prev_pri = aioreq_pri [$pri]
214 aioreq_nice $pri_adjust
215 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 $nfd = IO::AIO::get_fdlimit
233 IO::AIO::min_fdlimit $nfd
234 IO::AIO::sendfile $ofh, $ifh, $offset, $count
236 IO::AIO::fadvise $fh, $offset, $len, $advice
237 IO::AIO::fexecve $fh, $argv, $envp
238 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
240 IO::AIO::munmap $scalar
241 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
242 IO::AIO::madvise $scalar, $offset, $length, $advice
243 IO::AIO::mprotect $scalar, $offset, $length, $protect
244 IO::AIO::munlock $scalar, $offset = 0, $length = undef
245 IO::AIO::munlockall
246 # stat extensions
248 $counter = IO::AIO::st_gen
249 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
250 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
251 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
252 $seconds = IO::AIO::st_btimesec
253 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
254 # very much unportable syscalls
256 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
257 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
258 IO::AIO::tee $r_fh, $w_fh, $length, $flags
259 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
261 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
262 $fh = IO::AIO::eventfd [$initval, [$flags]]
264 $fh = IO::AIO::memfd_create $pathname[, $flags]
265 $fh = IO::AIO::timerfd_create $clockid[, $flags]
267 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
268 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
269 $fh = IO::AIO::pidfd_open $pid[, $flags]
271 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
272 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
273 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
275 $retval = IO::AIO::umount $path, $flags = 0
276 API NOTES
278 All the "aio_*" calls are more or less thin wrappers around the syscall
279 with the same name (sans "aio_"). The arguments are similar or
280 identical, and they all accept an additional (and optional) $callback
281 argument which must be a code reference. This code reference will be
282 called after the syscall has been executed in an asynchronous fashion.
283 The results of the request will be passed as arguments to the callback
284 (and, if an error occured, in $!) - for most requests the syscall
285 return code (e.g. most syscalls return "-1" on error, unlike perl,
286 which usually delivers "false").
287 Some requests (such as "aio_readdir") pass the actual results and
289 communicate failures by passing "undef".
290 All functions expecting a filehandle keep a copy of the filehandle
292 internally until the request has finished.
293 All functions return request objects of type IO::AIO::REQ that allow
295 further manipulation of those requests while they are in-flight.
296 The pathnames you pass to these routines should be absolute. The reason
298 for this is that at the time the request is being executed, the current
299 working directory could have changed. Alternatively, you can make sure
300 that you never change the current working directory anywhere in the
301 program and then use relative paths. You can also take advantage of
302 IO::AIOs working directory abstraction, that lets you specify paths
303 relative to some previously-opened "working directory object" - see the
304 description of the "IO::AIO::WD" class later in this document.
305 To encode pathnames as octets, either make sure you either: a) always
307 pass in filenames you got from outside (command line, readdir etc.)
308 without tinkering, b) are in your native filesystem encoding, c) use
309 the Encode module and encode your pathnames to the locale (or other)
310 encoding in effect in the user environment, d) use
311 Glib::filename_from_unicode on unicode filenames or e) use something
312 else to ensure your scalar has the correct contents.
313 This works, btw. independent of the internal UTF-8 bit, which IO::AIO
315 handles correctly whether it is set or not.
316 AIO REQUEST FUNCTIONS
318 $prev_pri = aioreq_pri [$pri]
319 Returns the priority value that would be used for the next request
320 and, if $pri is given, sets the priority for the next aio request.
321 The default priority is 0, the minimum and maximum priorities are
323 "-4" and 4, respectively. Requests with higher priority will be
324 serviced first.
325 The priority will be reset to 0 after each call to one of the
327 "aio_*" functions.
328 Example: open a file with low priority, then read something from it
330 with higher priority so the read request is serviced before other
331 low priority open requests (potentially spamming the cache):
332 aioreq_pri -3;
334 aio_open ..., sub {
335 return unless $_[0];
336 aioreq_pri -2;
338 aio_read $_[0], ..., sub {
339 ...
340 };
341 };
342 aioreq_nice $pri_adjust
344 Similar to "aioreq_pri", but subtracts the given value from the
345 current priority, so the effect is cumulative.
346 aio_open $pathname, $flags, $mode, $callback->($fh)
348 Asynchronously open or create a file and call the callback with a
349 newly created filehandle for the file (or "undef" in case of an
350 error).
351 The pathname passed to "aio_open" must be absolute. See API NOTES,
353 above, for an explanation.
354 The $flags argument is a bitmask. See the "Fcntl" module for a
356 list. They are the same as used by "sysopen".
357 Likewise, $mode specifies the mode of the newly created file, if it
359 didn't exist and "O_CREAT" has been given, just like perl's
360 "sysopen", except that it is mandatory (i.e. use 0 if you don't
361 create new files, and 0666 or 0777 if you do). Note that the $mode
362 will be modified by the umask in effect then the request is being
363 executed, so better never change the umask.
364 Example:
366 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
368 if ($_[0]) {
369 print "open successful, fh is $_[0]\n";
370 ...
371 } else {
372 die "open failed: $!\n";
373 }
374 };
375 In addition to all the common open modes/flags ("O_RDONLY",
377 "O_WRONLY", "O_RDWR", "O_CREAT", "O_TRUNC", "O_EXCL" and
378 "O_APPEND"), the following POSIX and non-POSIX constants are
379 available (missing ones on your system are, as usual, 0):
380 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
382 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
383 "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", "O_TTY_INIT"
384 and "O_ACCMODE".
385 aio_close $fh, $callback->($status)
387 Asynchronously close a file and call the callback with the result
388 code.
389 Unfortunately, you can't do this to perl. Perl insists very
391 strongly on closing the file descriptor associated with the
392 filehandle itself.
393 Therefore, "aio_close" will not close the filehandle - instead it
395 will use dup2 to overwrite the file descriptor with the write-end
396 of a pipe (the pipe fd will be created on demand and will be
397 cached).
398 Or in other words: the file descriptor will be closed, but it will
400 not be free for reuse until the perl filehandle is closed.
401 aio_seek $fh, $offset, $whence, $callback->($offs)
403 Seeks the filehandle to the new $offset, similarly to perl's
404 "sysseek". The $whence can use the traditional values (0 for
405 "IO::AIO::SEEK_SET", 1 for "IO::AIO::SEEK_CUR" or 2 for
406 "IO::AIO::SEEK_END").
407 The resulting absolute offset will be passed to the callback, or
409 "-1" in case of an error.
410 In theory, the $whence constants could be different than the
412 corresponding values from Fcntl, but perl guarantees they are the
413 same, so don't panic.
414 As a GNU/Linux (and maybe Solaris) extension, also the constants
416 "IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if
417 they could be found. No guarantees about suitability for use in
418 "aio_seek" or Perl's "sysseek" can be made though, although I would
419 naively assume they "just work".
420 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
422 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
423 Reads or writes $length bytes from or to the specified $fh and
424 $offset into the scalar given by $data and offset $dataoffset and
425 calls the callback with the actual number of bytes transferred (or
426 -1 on error, just like the syscall).
427 "aio_read" will, like "sysread", shrink or grow the $data scalar to
429 offset plus the actual number of bytes read.
430 If $offset is undefined, then the current file descriptor offset
432 will be used (and updated), otherwise the file descriptor offset
433 will not be changed by these calls.
434 If $length is undefined in "aio_write", use the remaining length of
436 $data.
437 If $dataoffset is less than zero, it will be counted from the end
439 of $data.
440 The $data scalar MUST NOT be modified in any way while the request
442 is outstanding. Modifying it can result in segfaults or World War
443 III (if the necessary/optional hardware is installed).
444 Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
446 offset 0 within the scalar:
447 aio_read $fh, 7, 15, $buffer, 0, sub {
449 $_[0] > 0 or die "read error: $!";
450 print "read $_[0] bytes: <$buffer>\n";
451 };
452 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
454 Tries to copy $length bytes from $in_fh to $out_fh. It starts
455 reading at byte offset $in_offset, and starts writing at the
456 current file offset of $out_fh. Because of that, it is not safe to
457 issue more than one "aio_sendfile" per $out_fh, as they will
458 interfere with each other. The same $in_fh works fine though, as
459 this function does not move or use the file offset of $in_fh.
460 Please note that "aio_sendfile" can read more bytes from $in_fh
462 than are written, and there is no way to find out how many more
463 bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
464 only provides the number of bytes written to $out_fh. Only if the
465 result value equals $length one can assume that $length bytes have
466 been read.
467 Unlike with other "aio_" functions, it makes a lot of sense to use
469 "aio_sendfile" on non-blocking sockets, as long as one end
470 (typically the $in_fh) is a file - the file I/O will then be
471 asynchronous, while the socket I/O will be non-blocking. Note,
472 however, that you can run into a trap where "aio_sendfile" reads
473 some data with readahead, then fails to write all data, and when
474 the socket is ready the next time, the data in the cache is already
475 lost, forcing "aio_sendfile" to again hit the disk. Explicit
476 "aio_read" + "aio_write" let's you better control resource usage.
477 This call tries to make use of a native "sendfile"-like syscall to
479 provide zero-copy operation. For this to work, $out_fh should refer
480 to a socket, and $in_fh should refer to an mmap'able file.
481 If a native sendfile cannot be found or it fails with "ENOSYS",
483 "EINVAL", "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
484 "ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
485 any type of filehandle regardless of the limitations of the
486 operating system.
487 As native sendfile syscalls (as practically any non-POSIX interface
489 hacked together in a hurry to improve benchmark numbers) tend to be
490 rather buggy on many systems, this implementation tries to work
491 around some known bugs in Linux and FreeBSD kernels (probably
492 others, too), but that might fail, so you really really should
493 check the return value of "aio_sendfile" - fewer bytes than
494 expected might have been transferred.
495 aio_readahead $fh,$offset,$length, $callback->($retval)
497 "aio_readahead" populates the page cache with data from a file so
498 that subsequent reads from that file will not block on disk I/O.
499 The $offset argument specifies the starting point from which data
500 is to be read and $length specifies the number of bytes to be read.
501 I/O is performed in whole pages, so that offset is effectively
502 rounded down to a page boundary and bytes are read up to the next
503 page boundary greater than or equal to (off-set+length).
504 "aio_readahead" does not read beyond the end of the file. The
505 current file offset of the file is left unchanged.
506 If that syscall doesn't exist (likely if your kernel isn't Linux)
508 it will be emulated by simply reading the data, which would have a
509 similar effect.
510 aio_stat $fh_or_path, $callback->($status)
512 aio_lstat $fh, $callback->($status)
513 Works almost exactly like perl's "stat" or "lstat" in void context.
514 The callback will be called after the stat and the results will be
515 available using "stat _" or "-s _" and other tests (with the
516 exception of "-B" and "-T").
517 The pathname passed to "aio_stat" must be absolute. See API NOTES,
519 above, for an explanation.
520 Currently, the stats are always 64-bit-stats, i.e. instead of
522 returning an error when stat'ing a large file, the results will be
523 silently truncated unless perl itself is compiled with large file
524 support.
525 To help interpret the mode and dev/rdev stat values, IO::AIO offers
527 the following constants and functions (if not implemented, the
528 constants will be 0 and the functions will either "croak" or fall
529 back on traditional behaviour).
530 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
532 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
533 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
534 To access higher resolution stat timestamps, see "SUBSECOND STAT
536 TIME ACCESS".
537 Example: Print the length of /etc/passwd:
539 aio_stat "/etc/passwd", sub {
541 $_[0] and die "stat failed: $!";
542 print "size is ", -s _, "\n";
543 };
544 aio_statvfs $fh_or_path, $callback->($statvfs)
546 Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
547 whether a file handle or path was passed.
548 On success, the callback is passed a hash reference with the
550 following members: "bsize", "frsize", "blocks", "bfree", "bavail",
551 "files", "ffree", "favail", "fsid", "flag" and "namemax". On
552 failure, "undef" is passed.
553 The following POSIX IO::AIO::ST_* constants are defined:
555 "ST_RDONLY" and "ST_NOSUID".
556 The following non-POSIX IO::AIO::ST_* flag masks are defined to
558 their correct value when available, or to 0 on systems that do not
559 support them: "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
560 "ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
561 "ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
562 Example: stat "/wd" and dump out the data if successful.
564 aio_statvfs "/wd", sub {
566 my $f = $_[0]
567 or die "statvfs: $!";
568 use Data::Dumper;
570 say Dumper $f;
571 };
572 # result:
574 {
575 bsize => 1024,
576 bfree => 4333064312,
577 blocks => 10253828096,
578 files => 2050765568,
579 flag => 4096,
580 favail => 2042092649,
581 bavail => 4333064312,
582 ffree => 2042092649,
583 namemax => 255,
584 frsize => 1024,
585 fsid => 1810
586 }
587 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
589 Works like perl's "utime" function (including the special case of
590 $atime and $mtime being undef). Fractional times are supported if
591 the underlying syscalls support them.
592 When called with a pathname, uses utimensat(2) or utimes(2) if
594 available, otherwise utime(2). If called on a file descriptor, uses
595 futimens(2) or futimes(2) if available, otherwise returns ENOSYS,
596 so this is not portable.
597 Examples:
599 # set atime and mtime to current time (basically touch(1)):
601 aio_utime "path", undef, undef;
602 # set atime to current time and mtime to beginning of the epoch:
603 aio_utime "path", time, undef; # undef==0
604 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
606 Works like perl's "chown" function, except that "undef" for either
607 $uid or $gid is being interpreted as "do not change" (but -1 can
608 also be used).
609 Examples:
611 # same as "chown root path" in the shell:
613 aio_chown "path", 0, -1;
614 # same as above:
615 aio_chown "path", 0, undef;
616 aio_truncate $fh_or_path, $offset, $callback->($status)
618 Works like truncate(2) or ftruncate(2).
619 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
621 Allocates or frees disk space according to the $mode argument. See
622 the linux "fallocate" documentation for details.
623 $mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
625 space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
626 IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
627 IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
629 (without leaving a hole), "FALLOC_FL_ZERO_RANGE", to zero a range,
630 "FALLOC_FL_INSERT_RANGE" to insert a range and
631 "FALLOC_FL_UNSHARE_RANGE" to unshare shared blocks (see your
632 fallocate(2) manpage).
633 The file system block size used by "fallocate" is presumably the
635 "f_bsize" returned by "statvfs", but different filesystems and
636 filetypes can dictate other limitations.
637 If "fallocate" isn't available or cannot be emulated (currently no
639 emulation will be attempted), passes "-1" and sets $! to "ENOSYS".
640 aio_chmod $fh_or_path, $mode, $callback->($status)
642 Works like perl's "chmod" function.
643 aio_unlink $pathname, $callback->($status)
645 Asynchronously unlink (delete) a file and call the callback with
646 the result code.
647 aio_mknod $pathname, $mode, $dev, $callback->($status)
649 [EXPERIMENTAL]
650 Asynchronously create a device node (or fifo). See mknod(2).
652 The only (POSIX-) portable way of calling this function is:
654 aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
656 See "aio_stat" for info about some potentially helpful extra
658 constants and functions.
659 aio_link $srcpath, $dstpath, $callback->($status)
661 Asynchronously create a new link to the existing object at $srcpath
662 at the path $dstpath and call the callback with the result code.
663 aio_symlink $srcpath, $dstpath, $callback->($status)
665 Asynchronously create a new symbolic link to the existing object at
666 $srcpath at the path $dstpath and call the callback with the result
667 code.
668 aio_readlink $pathname, $callback->($link)
670 Asynchronously read the symlink specified by $path and pass it to
671 the callback. If an error occurs, nothing or undef gets passed to
672 the callback.
673 aio_realpath $pathname, $callback->($path)
675 Asynchronously make the path absolute and resolve any symlinks in
676 $path. The resulting path only consists of directories (same as
677 Cwd::realpath).
678 This request can be used to get the absolute path of the current
680 working directory by passing it a path of . (a single dot).
681 aio_rename $srcpath, $dstpath, $callback->($status)
683 Asynchronously rename the object at $srcpath to $dstpath, just as
684 rename(2) and call the callback with the result code.
685 On systems that support the AIO::WD working directory abstraction
687 natively, the case "[$wd, "."]" as $srcpath is specialcased -
688 instead of failing, "rename" is called on the absolute path of $wd.
689 aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
691 Basically a version of "aio_rename" with an additional $flags
692 argument. Calling this with "$flags=0" is the same as calling
693 "aio_rename".
694 Non-zero flags are currently only supported on GNU/Linux systems
696 that support renameat2. Other systems fail with "ENOSYS" in this
697 case.
698 The following constants are available (missing ones are, as usual
700 0), see renameat2(2) for details:
701 "IO::AIO::RENAME_NOREPLACE", "IO::AIO::RENAME_EXCHANGE" and
703 "IO::AIO::RENAME_WHITEOUT".
704 aio_mkdir $pathname, $mode, $callback->($status)
706 Asynchronously mkdir (create) a directory and call the callback
707 with the result code. $mode will be modified by the umask at the
708 time the request is executed, so do not change your umask.
709 aio_rmdir $pathname, $callback->($status)
711 Asynchronously rmdir (delete) a directory and call the callback
712 with the result code.
713 On systems that support the AIO::WD working directory abstraction
715 natively, the case "[$wd, "."]" is specialcased - instead of
716 failing, "rmdir" is called on the absolute path of $wd.
717 aio_readdir $pathname, $callback->($entries)
719 Unlike the POSIX call of the same name, "aio_readdir" reads an
720 entire directory (i.e. opendir + readdir + closedir). The entries
721 will not be sorted, and will NOT include the "." and ".." entries.
722 The callback is passed a single argument which is either "undef" or
724 an array-ref with the filenames.
725 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
727 Quite similar to "aio_readdir", but the $flags argument allows one
728 to tune behaviour and output format. In case of an error, $entries
729 will be "undef".
730 The flags are a combination of the following constants, ORed
732 together (the flags will also be passed to the callback, possibly
733 modified):
734 IO::AIO::READDIR_DENTS
736 Normally the callback gets an arrayref consisting of names only
737 (as with "aio_readdir"). If this flag is set, then the callback
738 gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
739 describing a single directory entry in more detail:
740 $name is the name of the entry.
742 $type is one of the "IO::AIO::DT_xxx" constants:
744 "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
746 "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
747 "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
748 "IO::AIO::DT_UNKNOWN" means just that: readdir does not know.
750 If you need to know, you have to run stat yourself. Also, for
751 speed/memory reasons, the $type scalars are read-only: you must
752 not modify them.
753 $inode is the inode number (which might not be exact on systems
755 with 64 bit inode numbers and 32 bit perls). This field has
756 unspecified content on systems that do not deliver the inode
757 information.
758 IO::AIO::READDIR_DIRS_FIRST
760 When this flag is set, then the names will be returned in an
761 order where likely directories come first, in optimal stat
762 order. This is useful when you need to quickly find
763 directories, or you want to find all directories while avoiding
764 to stat() each entry.
765 If the system returns type information in readdir, then this is
767 used to find directories directly. Otherwise, likely
768 directories are names beginning with ".", or otherwise names
769 with no dots, of which names with short names are tried first.
770 IO::AIO::READDIR_STAT_ORDER
772 When this flag is set, then the names will be returned in an
773 order suitable for stat()'ing each one. That is, when you plan
774 to stat() most or all files in the given directory, then the
775 returned order will likely be faster.
776 If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
778 specified, then the likely dirs come first, resulting in a less
779 optimal stat order for stat'ing all entries, but likely a more
780 optimal order for finding subdirectories.
781 IO::AIO::READDIR_FOUND_UNKNOWN
783 This flag should not be set when calling "aio_readdirx".
784 Instead, it is being set by "aio_readdirx", when any of the
785 $type's found were "IO::AIO::DT_UNKNOWN". The absence of this
786 flag therefore indicates that all $type's are known, which can
787 be used to speed up some algorithms.
788 aio_slurp $pathname, $offset, $length, $data, $callback->($status)
790 Opens, reads and closes the given file. The data is put into $data,
791 which is resized as required.
792 If $offset is negative, then it is counted from the end of the
794 file.
795 If $length is zero, then the remaining length of the file is used.
797 Also, in this case, the same limitations to modifying $data apply
798 as when IO::AIO::mmap is used, i.e. it must only be modified in-
799 place with "substr". If the size of the file is known, specifying a
800 non-zero $length results in a performance advantage.
801 This request is similar to the older "aio_load" request, but since
803 it is a single request, it might be more efficient to use.
804 Example: load /etc/passwd into $passwd.
806 my $passwd;
808 aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
809 $_[0] >= 0
810 or die "/etc/passwd: $!\n";
811 printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
813 print $passwd;
814 };
815 IO::AIO::flush;
816 aio_load $pathname, $data, $callback->($status)
818 This is a composite request that tries to fully load the given file
819 into memory. Status is the same as with aio_read.
820 Using "aio_slurp" might be more efficient, as it is a single
822 request.
823 aio_copy $srcpath, $dstpath, $callback->($status)
825 Try to copy the file (directories not supported as either source or
826 destination) from $srcpath to $dstpath and call the callback with a
827 status of 0 (ok) or "-1" (error, see $!).
828 Existing destination files will be truncated.
830 This is a composite request that creates the destination file with
832 mode 0200 and copies the contents of the source file into it using
833 "aio_sendfile", followed by restoring atime, mtime, access mode and
834 uid/gid, in that order.
835 If an error occurs, the partial destination file will be unlinked,
837 if possible, except when setting atime, mtime, access mode and
838 uid/gid, where errors are being ignored.
839 aio_move $srcpath, $dstpath, $callback->($status)
841 Try to move the file (directories not supported as either source or
842 destination) from $srcpath to $dstpath and call the callback with a
843 status of 0 (ok) or "-1" (error, see $!).
844 This is a composite request that tries to rename(2) the file first;
846 if rename fails with "EXDEV", it copies the file with "aio_copy"
847 and, if that is successful, unlinks the $srcpath.
848 aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
850 Scans a directory (similar to "aio_readdir") but additionally tries
851 to efficiently separate the entries of directory $path into two
852 sets of names, directories you can recurse into (directories), and
853 ones you cannot recurse into (everything else, including symlinks
854 to directories).
855 "aio_scandir" is a composite request that generates many sub
857 requests. $maxreq specifies the maximum number of outstanding aio
858 requests that this function generates. If it is "<= 0", then a
859 suitable default will be chosen (currently 4).
860 On error, the callback is called without arguments, otherwise it
862 receives two array-refs with path-relative entry names.
863 Example:
865 aio_scandir $dir, 0, sub {
867 my ($dirs, $nondirs) = @_;
868 print "real directories: @$dirs\n";
869 print "everything else: @$nondirs\n";
870 };
871 Implementation notes.
873 The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
875 can.
876 If readdir returns file type information, then this is used
878 directly to find directories.
879 Otherwise, after reading the directory, the modification time, size
881 etc. of the directory before and after the readdir is checked, and
882 if they match (and isn't the current time), the link count will be
883 used to decide how many entries are directories (if >= 2).
884 Otherwise, no knowledge of the number of subdirectories will be
885 assumed.
886 Then entries will be sorted into likely directories a non-initial
888 dot currently) and likely non-directories (see "aio_readdirx").
889 Then every entry plus an appended "/." will be "stat"'ed, likely
890 directories first, in order of their inode numbers. If that
891 succeeds, it assumes that the entry is a directory or a symlink to
892 directory (which will be checked separately). This is often faster
893 than stat'ing the entry itself because filesystems might detect the
894 type of the entry without reading the inode data (e.g. ext2fs
895 filetype feature), even on systems that cannot return the filetype
896 information on readdir.
897 If the known number of directories (link count - 2) has been
899 reached, the rest of the entries is assumed to be non-directories.
900 This only works with certainty on POSIX (= UNIX) filesystems, which
902 fortunately are the vast majority of filesystems around.
903 It will also likely work on non-POSIX filesystems with reduced
905 efficiency as those tend to return 0 or 1 as link counts, which
906 disables the directory counting heuristic.
907 aio_rmtree $pathname, $callback->($status)
909 Delete a directory tree starting (and including) $path, return the
910 status of the final "rmdir" only. This is a composite request that
911 uses "aio_scandir" to recurse into and rmdir directories, and
912 unlink everything else.
913 aio_fcntl $fh, $cmd, $arg, $callback->($status)
915 aio_ioctl $fh, $request, $buf, $callback->($status)
916 These work just like the "fcntl" and "ioctl" built-in functions,
917 except they execute asynchronously and pass the return value to the
918 callback.
919 Both calls can be used for a lot of things, some of which make more
921 sense to run asynchronously in their own thread, while some others
922 make less sense. For example, calls that block waiting for external
923 events, such as locking, will also lock down an I/O thread while it
924 is waiting, which can deadlock the whole I/O system. At the same
925 time, there might be no alternative to using a thread to wait.
926 So in general, you should only use these calls for things that do
928 (filesystem) I/O, not for things that wait for other events
929 (network, other processes), although if you are careful and know
930 what you are doing, you still can.
931 The following constants are available and can be used for normal
933 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
934 "F_DUPFD_CLOEXEC",
936 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
938 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
940 "FIDEDUPERANGE".
941 "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
943 "F_SEAL_GROW" and "F_SEAL_WRITE".
944 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
946 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
947 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
949 "FS_IOC_SET_ENCRYPTION_POLICY", "FS_IOC_GET_ENCRYPTION_PWSALT",
950 "FS_IOC_GET_ENCRYPTION_POLICY", "FS_KEY_DESCRIPTOR_SIZE".
951 "FS_SECRM_FL", "FS_UNRM_FL", "FS_COMPR_FL", "FS_SYNC_FL",
953 "FS_IMMUTABLE_FL", "FS_APPEND_FL", "FS_NODUMP_FL", "FS_NOATIME_FL",
954 "FS_DIRTY_FL", "FS_COMPRBLK_FL", "FS_NOCOMP_FL", "FS_ENCRYPT_FL",
955 "FS_BTREE_FL", "FS_INDEX_FL", "FS_JOURNAL_DATA_FL", "FS_NOTAIL_FL",
956 "FS_DIRSYNC_FL", "FS_TOPDIR_FL", "FS_FL_USER_MODIFIABLE".
957 "FS_XFLAG_REALTIME", "FS_XFLAG_PREALLOC", "FS_XFLAG_IMMUTABLE",
959 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
960 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
961 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
962 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
963 "FS_XFLAG_HASATTR",
964 "BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
966 "BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
967 "BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET",
968 "BLKGETSIZE64",
969 aio_sync $callback->($status)
971 Asynchronously call sync and call the callback when finished.
972 aio_fsync $fh, $callback->($status)
974 Asynchronously call fsync on the given filehandle and call the
975 callback with the fsync result code.
976 aio_fdatasync $fh, $callback->($status)
978 Asynchronously call fdatasync on the given filehandle and call the
979 callback with the fdatasync result code.
980 If this call isn't available because your OS lacks it or it
982 couldn't be detected, it will be emulated by calling "fsync"
983 instead.
984 aio_syncfs $fh, $callback->($status)
986 Asynchronously call the syncfs syscall to sync the filesystem
987 associated to the given filehandle and call the callback with the
988 syncfs result code. If syncfs is not available, calls sync(), but
989 returns "-1" and sets errno to "ENOSYS" nevertheless.
990 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
992 Sync the data portion of the file specified by $offset and $length
993 to disk (but NOT the metadata), by calling the Linux-specific
994 sync_file_range call. If sync_file_range is not available or it
995 returns ENOSYS, then fdatasync or fsync is being substituted.
996 $flags can be a combination of
998 "IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
999 "IO::AIO::SYNC_FILE_RANGE_WRITE" and
1000 "IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
1001 manpage for details.
1002 aio_pathsync $pathname, $callback->($status)
1004 This request tries to open, fsync and close the given path. This is
1005 a composite request intended to sync directories after directory
1006 operations (E.g. rename). This might not work on all operating
1007 systems or have any specific effect, but usually it makes sure that
1008 directory changes get written to disc. It works for anything that
1009 can be opened for read-only, not just directories.
1010 Future versions of this function might fall back to other methods
1012 when "fsync" on the directory fails (such as calling "sync").
1013 Passes 0 when everything went ok, and "-1" on error.
1015 aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC,
1017 $callback->($status)
1018 This is a rather advanced IO::AIO call, which only works on
1019 mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
1020 also works on data scalars managed by the Sys::Mmap or Mmap
1021 modules, note that the scalar must only be modified in-place while
1022 an aio operation is pending on it).
1023 It calls the "msync" function of your OS, if available, with the
1025 memory area starting at $offset in the string and ending $length
1026 bytes later. If $length is negative, counts from the end, and if
1027 $length is "undef", then it goes till the end of the string. The
1028 flags can be either "IO::AIO::MS_ASYNC" or "IO::AIO::MS_SYNC", plus
1029 an optional "IO::AIO::MS_INVALIDATE".
1030 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
1032 $callback->($status)
1033 This is a rather advanced IO::AIO call, which works best on
1034 mmap(2)ed scalars.
1035 It touches (reads or writes) all memory pages in the specified
1037 range inside the scalar. All caveats and parameters are the same as
1038 for "aio_msync", above, except for flags, which must be either 0
1039 (which reads all pages and ensures they are instantiated) or
1040 "IO::AIO::MT_MODIFY", which modifies the memory pages (by reading
1041 and writing an octet from it, which dirties the page).
1042 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1044 This is a rather advanced IO::AIO call, which works best on
1045 mmap(2)ed scalars.
1046 It reads in all the pages of the underlying storage into memory (if
1048 any) and locks them, so they are not getting swapped/paged out or
1049 removed.
1050 If $length is undefined, then the scalar will be locked till the
1052 end.
1053 On systems that do not implement "mlock", this function returns
1055 "-1" and sets errno to "ENOSYS".
1056 Note that the corresponding "munlock" is synchronous and is
1058 documented under "MISCELLANEOUS FUNCTIONS".
1059 Example: open a file, mmap and mlock it - both will be undone when
1061 $data gets destroyed.
1062 open my $fh, "<", $path or die "$path: $!";
1064 my $data;
1065 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1066 aio_mlock $data; # mlock in background
1067 aio_mlockall $flags, $callback->($status)
1069 Calls the "mlockall" function with the given $flags (a combination
1070 of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
1071 "IO::AIO::MCL_ONFAULT").
1072 On systems that do not implement "mlockall", this function returns
1074 "-1" and sets errno to "ENOSYS". Similarly, flag combinations not
1075 supported by the system result in a return value of "-1" with errno
1076 being set to "EINVAL".
1077 Note that the corresponding "munlockall" is synchronous and is
1079 documented under "MISCELLANEOUS FUNCTIONS".
1080 Example: asynchronously lock all current and future pages into
1082 memory.
1083 aio_mlockall IO::AIO::MCL_FUTURE;
1085 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1087 Queries the extents of the given file (by calling the Linux
1088 "FIEMAP" ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt>
1089 for details). If the ioctl is not available on your OS, then this
1090 request will fail with "ENOSYS".
1091 $start is the starting offset to query extents for, $length is the
1093 size of the range to query - if it is "undef", then the whole file
1094 will be queried.
1095 $flags is a combination of flags ("IO::AIO::FIEMAP_FLAG_SYNC" or
1097 "IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
1098 also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
1099 query the data portion.
1100 $count is the maximum number of extent records to return. If it is
1102 "undef", then IO::AIO queries all extents of the range. As a very
1103 special case, if it is 0, then the callback receives the number of
1104 extents instead of the extents themselves (which is unreliable, see
1105 below).
1106 If an error occurs, the callback receives no arguments. The special
1108 "errno" value "IO::AIO::EBADR" is available to test for flag
1109 errors.
1110 Otherwise, the callback receives an array reference with extent
1112 structures. Each extent structure is an array reference itself,
1113 with the following members:
1114 [$logical, $physical, $length, $flags]
1116 Flags is any combination of the following flag values (typically
1118 either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
1119 "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
1121 "IO::AIO::FIEMAP_EXTENT_DELALLOC",
1122 "IO::AIO::FIEMAP_EXTENT_ENCODED",
1123 "IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
1124 "IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
1125 "IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
1126 "IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
1127 "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
1128 or "IO::AIO::FIEMAP_EXTENT_SHARED".
1129 At the time of this writing (Linux 3.2), this request is unreliable
1131 unless $count is "undef", as the kernel has all sorts of bugs
1132 preventing it to return all extents of a range for files with a
1133 large number of extents. The code (only) works around all these
1134 issues if $count is "undef".
1135 aio_group $callback->(...)
1137 This is a very special aio request: Instead of doing something, it
1138 is a container for other aio requests, which is useful if you want
1139 to bundle many requests into a single, composite, request with a
1140 definite callback and the ability to cancel the whole request with
1141 its subrequests.
1142 Returns an object of class IO::AIO::GRP. See its documentation
1144 below for more info.
1145 Example:
1147 my $grp = aio_group sub {
1149 print "all stats done\n";
1150 };
1151 add $grp
1153 (aio_stat ...),
1154 (aio_stat ...),
1155 ...;
1156 aio_nop $callback->()
1158 This is a special request - it does nothing in itself and is only
1159 used for side effects, such as when you want to add a dummy request
1160 to a group so that finishing the requests in the group depends on
1161 executing the given code.
1162 While this request does nothing, it still goes through the
1164 execution phase and still requires a worker thread. Thus, the
1165 callback will not be executed immediately but only after other
1166 requests in the queue have entered their execution phase. This can
1167 be used to measure request latency.
1168 IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED*
1170 Mainly used for debugging and benchmarking, this aio request puts
1171 one of the request workers to sleep for the given time.
1172 While it is theoretically handy to have simple I/O scheduling
1174 requests like sleep and file handle readable/writable, the overhead
1175 this creates is immense (it blocks a thread for a long time) so do
1176 not use this function except to put your application under
1177 artificial I/O pressure.
1178 IO::AIO::WD - multiple working directories
1180 Your process only has one current working directory, which is used by
1181 all threads. This makes it hard to use relative paths (some other
1182 component could call "chdir" at any time, and it is hard to control
1183 when the path will be used by IO::AIO).
1184 One solution for this is to always use absolute paths. This usually
1186 works, but can be quite slow (the kernel has to walk the whole path on
1187 every access), and can also be a hassle to implement.
1188 Newer POSIX systems have a number of functions (openat, fdopendir,
1190 futimensat and so on) that make it possible to specify working
1191 directories per operation.
1192 For portability, and because the clowns who "designed", or shall I
1194 write, perpetrated this new interface were obviously half-drunk, this
1195 abstraction cannot be perfect, though.
1196 IO::AIO allows you to convert directory paths into a so-called
1198 IO::AIO::WD object. This object stores the canonicalised, absolute
1199 version of the path, and on systems that allow it, also a directory
1200 file descriptor.
1201 Everywhere where a pathname is accepted by IO::AIO (e.g. in "aio_stat"
1203 or "aio_unlink"), one can specify an array reference with an
1204 IO::AIO::WD object and a pathname instead (or the IO::AIO::WD object
1205 alone, which gets interpreted as "[$wd, "."]"). If the pathname is
1206 absolute, the IO::AIO::WD object is ignored, otherwise the pathname is
1207 resolved relative to that IO::AIO::WD object.
1208 For example, to get a wd object for /etc and then stat passwd inside,
1210 you would write:
1211 aio_wd "/etc", sub {
1213 my $etcdir = shift;
1214 # although $etcdir can be undef on error, there is generally no reason
1216 # to check for errors here, as aio_stat will fail with ENOENT
1217 # when $etcdir is undef.
1218 aio_stat [$etcdir, "passwd"], sub {
1220 # yay
1221 };
1222 };
1223 The fact that "aio_wd" is a request and not a normal function shows
1225 that creating an IO::AIO::WD object is itself a potentially blocking
1226 operation, which is why it is done asynchronously.
1227 To stat the directory obtained with "aio_wd" above, one could write
1229 either of the following three request calls:
1230 aio_lstat "/etc" , sub { ... # pathname as normal string
1232 aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
1233 aio_lstat $wd , sub { ... # shorthand for the previous
1234 As with normal pathnames, IO::AIO keeps a copy of the working directory
1236 object and the pathname string, so you could write the following
1237 without causing any issues due to $path getting reused:
1238 my $path = [$wd, undef];
1240 for my $name (qw(abc def ghi)) {
1242 $path->[1] = $name;
1243 aio_stat $path, sub {
1244 # ...
1245 };
1246 }
1247 There are some caveats: when directories get renamed (or deleted), the
1249 pathname string doesn't change, so will point to the new directory (or
1250 nowhere at all), while the directory fd, if available on the system,
1251 will still point to the original directory. Most functions accepting a
1252 pathname will use the directory fd on newer systems, and the string on
1253 older systems. Some functions (such as "aio_realpath") will always rely
1254 on the string form of the pathname.
1255 So this functionality is mainly useful to get some protection against
1257 "chdir", to easily get an absolute path out of a relative path for
1258 future reference, and to speed up doing many operations in the same
1259 directory (e.g. when stat'ing all files in a directory).
1260 The following functions implement this working directory abstraction:
1262 aio_wd $pathname, $callback->($wd)
1264 Asynchonously canonicalise the given pathname and convert it to an
1265 IO::AIO::WD object representing it. If possible and supported on
1266 the system, also open a directory fd to speed up pathname
1267 resolution relative to this working directory.
1268 If something goes wrong, then "undef" is passwd to the callback
1270 instead of a working directory object and $! is set appropriately.
1271 Since passing "undef" as working directory component of a pathname
1272 fails the request with "ENOENT", there is often no need for error
1273 checking in the "aio_wd" callback, as future requests using the
1274 value will fail in the expected way.
1275 IO::AIO::CWD
1277 This is a compile time constant (object) that represents the
1278 process current working directory.
1279 Specifying this object as working directory object for a pathname
1281 is as if the pathname would be specified directly, without a
1282 directory object. For example, these calls are functionally
1283 identical:
1284 aio_stat "somefile", sub { ... };
1286 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1287 To recover the path associated with an IO::AIO::WD object, you can use
1289 "aio_realpath":
1290 aio_realpath $wd, sub {
1292 warn "path is $_[0]\n";
1293 };
1294 Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir"
1296 sometimes, fall back to using an absolue path.
1297 IO::AIO::REQ CLASS
1299 All non-aggregate "aio_*" functions return an object of this class when
1300 called in non-void context.
1301 cancel $req
1303 Cancels the request, if possible. Has the effect of skipping
1304 execution when entering the execute state and skipping calling the
1305 callback when entering the the result state, but will leave the
1306 request otherwise untouched (with the exception of readdir). That
1307 means that requests that currently execute will not be stopped and
1308 resources held by the request will not be freed prematurely.
1309 cb $req $callback->(...)
1311 Replace (or simply set) the callback registered to the request.
1312 IO::AIO::GRP CLASS
1314 This class is a subclass of IO::AIO::REQ, so all its methods apply to
1315 objects of this class, too.
1316 A IO::AIO::GRP object is a special request that can contain multiple
1318 other aio requests.
1319 You create one by calling the "aio_group" constructing function with a
1321 callback that will be called when all contained requests have entered
1322 the "done" state:
1323 my $grp = aio_group sub {
1325 print "all requests are done\n";
1326 };
1327 You add requests by calling the "add" method with one or more
1329 "IO::AIO::REQ" objects:
1330 $grp->add (aio_unlink "...");
1332 add $grp aio_stat "...", sub {
1334 $_[0] or return $grp->result ("error");
1335 # add another request dynamically, if first succeeded
1337 add $grp aio_open "...", sub {
1338 $grp->result ("ok");
1339 };
1340 };
1341 This makes it very easy to create composite requests (see the source of
1343 "aio_move" for an application) that work and feel like simple requests.
1344 • The IO::AIO::GRP objects will be cleaned up during calls to
1346 "IO::AIO::poll_cb", just like any other request.
1347 • They can be canceled like any other request. Canceling will cancel
1349 not only the request itself, but also all requests it contains.
1350 • They can also can also be added to other IO::AIO::GRP objects.
1352 • You must not add requests to a group from within the group callback
1354 (or any later time).
1355 Their lifetime, simplified, looks like this: when they are empty, they
1357 will finish very quickly. If they contain only requests that are in the
1358 "done" state, they will also finish. Otherwise they will continue to
1359 exist.
1360 That means after creating a group you have some time to add requests
1362 (precisely before the callback has been invoked, which is only done
1363 within the "poll_cb"). And in the callbacks of those requests, you can
1364 add further requests to the group. And only when all those requests
1365 have finished will the the group itself finish.
1366 add $grp ...
1368 $grp->add (...)
1369 Add one or more requests to the group. Any type of IO::AIO::REQ can
1370 be added, including other groups, as long as you do not create
1371 circular dependencies.
1372 Returns all its arguments.
1374 $grp->cancel_subs
1376 Cancel all subrequests and clears any feeder, but not the group
1377 request itself. Useful when you queued a lot of events but got a
1378 result early.
1379 The group request will finish normally (you cannot add requests to
1381 the group).
1382 $grp->result (...)
1384 Set the result value(s) that will be passed to the group callback
1385 when all subrequests have finished and set the groups errno to the
1386 current value of errno (just like calling "errno" without an error
1387 number). By default, no argument will be passed and errno is zero.
1388 $grp->errno ([$errno])
1390 Sets the group errno value to $errno, or the current value of errno
1391 when the argument is missing.
1392 Every aio request has an associated errno value that is restored
1394 when the callback is invoked. This method lets you change this
1395 value from its default (0).
1396 Calling "result" will also set errno, so make sure you either set
1398 $! before the call to "result", or call c<errno> after it.
1399 feed $grp $callback->($grp)
1401 Sets a feeder/generator on this group: every group can have an
1402 attached generator that generates requests if idle. The idea behind
1403 this is that, although you could just queue as many requests as you
1404 want in a group, this might starve other requests for a potentially
1405 long time. For example, "aio_scandir" might generate hundreds of
1406 thousands of "aio_stat" requests, delaying any later requests for a
1407 long time.
1408 To avoid this, and allow incremental generation of requests, you
1410 can instead a group and set a feeder on it that generates those
1411 requests. The feed callback will be called whenever there are few
1412 enough (see "limit", below) requests active in the group itself and
1413 is expected to queue more requests.
1414 The feed callback can queue as many requests as it likes (i.e.
1416 "add" does not impose any limits).
1417 If the feed does not queue more requests when called, it will be
1419 automatically removed from the group.
1420 If the feed limit is 0 when this method is called, it will be set
1422 to 2 automatically.
1423 Example:
1425 # stat all files in @files, but only ever use four aio requests concurrently:
1427 my $grp = aio_group sub { print "finished\n" };
1429 limit $grp 4;
1430 feed $grp sub {
1431 my $file = pop @files
1432 or return;
1433 add $grp aio_stat $file, sub { ... };
1435 };
1436 limit $grp $num
1438 Sets the feeder limit for the group: The feeder will be called
1439 whenever the group contains less than this many requests.
1440 Setting the limit to 0 will pause the feeding process.
1442 The default value for the limit is 0, but note that setting a
1444 feeder automatically bumps it up to 2.
1445 SUPPORT FUNCTIONS
1447 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1448 $fileno = IO::AIO::poll_fileno
1450 Return the request result pipe file descriptor. This filehandle
1451 must be polled for reading by some mechanism outside this module
1452 (e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If
1453 the pipe becomes readable you have to call "poll_cb" to check the
1454 results.
1455 See "poll_cb" for an example.
1457 IO::AIO::poll_cb
1459 Process some requests that have reached the result phase (i.e. they
1460 have been executed but the results are not yet reported). You have
1461 to call this "regularly" to finish outstanding requests.
1462 Returns 0 if all events could be processed (or there were no events
1464 to process), or "-1" if it returned earlier for whatever reason.
1465 Returns immediately when no events are outstanding. The amount of
1466 events processed depends on the settings of
1467 "IO::AIO::max_poll_req", "IO::AIO::max_poll_time" and
1468 "IO::AIO::max_outstanding".
1469 If not all requests were processed for whatever reason, the poll
1471 file descriptor will still be ready when "poll_cb" returns, so
1472 normally you don't have to do anything special to have it called
1473 later.
1474 Apart from calling "IO::AIO::poll_cb" when the event filehandle
1476 becomes ready, it can be beneficial to call this function from
1477 loops which submit a lot of requests, to make sure the results get
1478 processed when they become available and not just when the loop is
1479 finished and the event loop takes over again. This function returns
1480 very fast when there are no outstanding requests.
1481 Example: Install an Event watcher that automatically calls
1483 IO::AIO::poll_cb with high priority (more examples can be found in
1484 the SYNOPSIS section, at the top of this document):
1485 Event->io (fd => IO::AIO::poll_fileno,
1487 poll => 'r', async => 1,
1488 cb => \&IO::AIO::poll_cb);
1489 IO::AIO::poll_wait
1491 Wait until either at least one request is in the result phase or no
1492 requests are outstanding anymore.
1493 This is useful if you want to synchronously wait for some requests
1495 to become ready, without actually handling them.
1496 See "nreqs" for an example.
1498 IO::AIO::poll
1500 Waits until some requests have been handled.
1501 Returns the number of requests processed, but is otherwise strictly
1503 equivalent to:
1504 IO::AIO::poll_wait, IO::AIO::poll_cb
1506 IO::AIO::flush
1508 Wait till all outstanding AIO requests have been handled.
1509 Strictly equivalent to:
1511 IO::AIO::poll_wait, IO::AIO::poll_cb
1513 while IO::AIO::nreqs;
1514 This function can be useful at program aborts, to make sure
1516 outstanding I/O has been done ("IO::AIO" uses an "END" block which
1517 already calls this function on normal exits), or when you are
1518 merely using "IO::AIO" for its more advanced functions, rather than
1519 for async I/O, e.g.:
1520 my ($dirs, $nondirs);
1522 IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1523 IO::AIO::flush;
1524 # $dirs, $nondirs are now set
1525 IO::AIO::max_poll_reqs $nreqs
1527 IO::AIO::max_poll_time $seconds
1528 These set the maximum number of requests (default 0, meaning
1529 infinity) that are being processed by "IO::AIO::poll_cb" in one
1530 call, respectively the maximum amount of time (default 0, meaning
1531 infinity) spent in "IO::AIO::poll_cb" to process requests (more
1532 correctly the mininum amount of time "poll_cb" is allowed to use).
1533 Setting "max_poll_time" to a non-zero value creates an overhead of
1535 one syscall per request processed, which is not normally a problem
1536 unless your callbacks are really really fast or your OS is really
1537 really slow (I am not mentioning Solaris here). Using
1538 "max_poll_reqs" incurs no overhead.
1539 Setting these is useful if you want to ensure some level of
1541 interactiveness when perl is not fast enough to process all
1542 requests in time.
1543 For interactive programs, values such as 0.01 to 0.1 should be
1545 fine.
1546 Example: Install an Event watcher that automatically calls
1548 IO::AIO::poll_cb with low priority, to ensure that other parts of
1549 the program get the CPU sometimes even under high AIO load.
1550 # try not to spend much more than 0.1s in poll_cb
1552 IO::AIO::max_poll_time 0.1;
1553 # use a low priority so other tasks have priority
1555 Event->io (fd => IO::AIO::poll_fileno,
1556 poll => 'r', nice => 1,
1557 cb => &IO::AIO::poll_cb);
1558 CONTROLLING THE NUMBER OF THREADS
1560 IO::AIO::min_parallel $nthreads
1562 Set the minimum number of AIO threads to $nthreads. The current
1563 default is 8, which means eight asynchronous operations can execute
1564 concurrently at any one time (the number of outstanding requests,
1565 however, is unlimited).
1566 IO::AIO starts threads only on demand, when an AIO request is
1568 queued and no free thread exists. Please note that queueing up a
1569 hundred requests can create demand for a hundred threads, even if
1570 it turns out that everything is in the cache and could have been
1571 processed faster by a single thread.
1572 It is recommended to keep the number of threads relatively low, as
1574 some Linux kernel versions will scale negatively with the number of
1575 threads (higher parallelity => MUCH higher latency). With current
1576 Linux 2.6 versions, 4-32 threads should be fine.
1577 Under most circumstances you don't need to call this function, as
1579 the module selects a default that is suitable for low to moderate
1580 load.
1581 IO::AIO::max_parallel $nthreads
1583 Sets the maximum number of AIO threads to $nthreads. If more than
1584 the specified number of threads are currently running, this
1585 function kills them. This function blocks until the limit is
1586 reached.
1587 While $nthreads are zero, aio requests get queued but not executed
1589 until the number of threads has been increased again.
1590 This module automatically runs "max_parallel 0" at program end, to
1592 ensure that all threads are killed and that there are no
1593 outstanding requests.
1594 Under normal circumstances you don't need to call this function.
1596 IO::AIO::max_idle $nthreads
1598 Limit the number of threads (default: 4) that are allowed to idle
1599 (i.e., threads that did not get a request to process within the
1600 idle timeout (default: 10 seconds). That means if a thread becomes
1601 idle while $nthreads other threads are also idle, it will free its
1602 resources and exit.
1603 This is useful when you allow a large number of threads (e.g. 100
1605 or 1000) to allow for extremely high load situations, but want to
1606 free resources under normal circumstances (1000 threads can easily
1607 consume 30MB of RAM).
1608 The default is probably ok in most situations, especially if thread
1610 creation is fast. If thread creation is very slow on your system
1611 you might want to use larger values.
1612 IO::AIO::idle_timeout $seconds
1614 Sets the minimum idle timeout (default 10) after which worker
1615 threads are allowed to exit. SEe "IO::AIO::max_idle".
1616 IO::AIO::max_outstanding $maxreqs
1618 Sets the maximum number of outstanding requests to $nreqs. If you
1619 do queue up more than this number of requests, the next call to
1620 "IO::AIO::poll_cb" (and other functions calling "poll_cb", such as
1621 "IO::AIO::flush" or "IO::AIO::poll") will block until the limit is
1622 no longer exceeded.
1623 In other words, this setting does not enforce a queue limit, but
1625 can be used to make poll functions block if the limit is exceeded.
1626 This is a bad function to use in interactive programs because it
1628 blocks, and a bad way to reduce concurrency because it is inexact.
1629 If you need to issue many requests without being able to call a
1630 poll function on demand, it is better to use an "aio_group"
1631 together with a feed callback.
1632 Its main use is in scripts without an event loop - when you want to
1634 stat a lot of files, you can write something like this:
1635 IO::AIO::max_outstanding 32;
1637 for my $path (...) {
1639 aio_stat $path , ...;
1640 IO::AIO::poll_cb;
1641 }
1642 IO::AIO::flush;
1644 The call to "poll_cb" inside the loop will normally return
1646 instantly, allowing the loop to progress, but as soon as more than
1647 32 requests are in-flight, it will block until some requests have
1648 been handled. This keeps the loop from pushing a large number of
1649 "aio_stat" requests onto the queue (which, with many paths to stat,
1650 can use up a lot of memory).
1651 The default value for "max_outstanding" is very large, so there is
1653 no practical limit on the number of outstanding requests.
1654 STATISTICAL INFORMATION
1656 IO::AIO::nreqs
1658 Returns the number of requests currently in the ready, execute or
1659 pending states (i.e. for which their callback has not been invoked
1660 yet).
1661 Example: wait till there are no outstanding requests anymore:
1663 IO::AIO::poll_wait, IO::AIO::poll_cb
1665 while IO::AIO::nreqs;
1666 IO::AIO::nready
1668 Returns the number of requests currently in the ready state (not
1669 yet executed).
1670 IO::AIO::npending
1672 Returns the number of requests currently in the pending state
1673 (executed, but not yet processed by poll_cb).
1674 SUBSECOND STAT TIME ACCESS
1676 Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
1678 generally find access/modification and change times with subsecond time
1679 accuracy of the system supports it, but perl's built-in functions only
1680 return the integer part.
1681 The following functions return the timestamps of the most recent stat
1683 with subsecond precision on most systems and work both after
1684 "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
1685 value is only meaningful after a successful "stat"/"lstat" call, or
1686 during/after a successful "aio_stat"/"aio_lstat" callback.
1687 This is similar to the Time::HiRes "stat" functions, but can return
1689 full resolution without rounding and work with standard perl "stat",
1690 alleviating the need to call the special "Time::HiRes" functions, which
1691 do not act like their perl counterparts.
1692 On operating systems or file systems where subsecond time resolution is
1694 not supported or could not be detected, a fractional part of 0 is
1695 returned, so it is always safe to call these functions.
1696 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
1698 IO::AIO::st_btime
1699 Return the access, modication, change or birth time, respectively,
1700 including fractional part. Due to the limited precision of floating
1701 point, the accuracy on most platforms is only a bit better than
1702 milliseconds for times around now - see the nsec function family,
1703 below, for full accuracy.
1704 File birth time is only available when the OS and perl support it
1706 (on FreeBSD and NetBSD at the time of this writing, although
1707 support is adaptive, so if your OS/perl gains support, IO::AIO can
1708 take advantage of it). On systems where it isn't available, 0 is
1709 currently returned, but this might change to "undef" in a future
1710 version.
1711 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1713 Returns access, modification, change and birth time all in one go,
1714 and maybe more times in the future version.
1715 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
1717 IO::AIO::st_ctimensec, IO::AIO::st_btimensec
1718 Return the fractional access, modifcation, change or birth time, in
1719 nanoseconds, as an integer in the range 0 to 999999999.
1720 Note that no accessors are provided for access, modification and
1722 change times - you need to get those from "stat _" if required
1723 ("int IO::AIO::st_atime" and so on will not generally give you the
1724 correct value).
1725 $seconds = IO::AIO::st_btimesec
1727 The (integral) seconds part of the file birth time, if available.
1728 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1730 Like the functions above, but returns all four times in one go (and
1731 maybe more in future versions).
1732 $counter = IO::AIO::st_gen
1734 Returns the generation counter (in practice this is just a random
1735 number) of the file. This is only available on platforms which have
1736 this member in their "struct stat" (most BSDs at the time of this
1737 writing) and generally only to the root usert. If unsupported, 0 is
1738 returned, but this might change to "undef" in a future version.
1739 Example: print the high resolution modification time of /etc, using
1741 "stat", and "IO::AIO::aio_stat".
1742 if (stat "/etc") {
1744 printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
1745 }
1746 IO::AIO::aio_stat "/etc", sub {
1748 $_[0]
1749 and return;
1750 printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
1752 };
1753 IO::AIO::flush;
1755 Output of the awbove on my system, showing reduced and full accuracy:
1757 stat(/etc) mtime: 1534043702.020808
1759 aio_stat(/etc) mtime: 1534043702.020807792
1760 MISCELLANEOUS FUNCTIONS
1762 IO::AIO implements some functions that are useful when you want to use
1764 some "Advanced I/O" function not available to in Perl, without going
1765 the "Asynchronous I/O" route. Many of these have an asynchronous
1766 "aio_*" counterpart.
1767 $retval = IO::AIO::fexecve $fh, $argv, $envp
1769 A more-or-less direct equivalent to the POSIX "fexecve" functions,
1770 which allows you to specify the program to be executed via a file
1771 descriptor (or handle). Returns "-1" and sets errno to "ENOSYS" if
1772 not available.
1773 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
1775 undef
1776 Calls the GNU/Linux mount syscall with the given arguments. All
1777 except $flags are strings, and if $data is "undef", a "NULL" will
1778 be passed.
1779 The following values for $flags are available:
1781 "IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
1783 "IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
1784 "IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
1785 "IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
1786 "IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
1787 "IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
1788 "IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
1789 "IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
1790 "IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
1791 "IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
1792 "IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
1793 "IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
1794 $retval = IO::AIO::umount $path, $flags = 0
1796 Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
1797 "umount" if $flags is 0, otherwqise always tries to call "umount2".
1798 The following $flags are available:
1800 "IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
1802 and "IO::AIO::UMOUNT_NOFOLLOW".
1803 $numfd = IO::AIO::get_fdlimit
1805 Tries to find the current file descriptor limit and returns it, or
1806 "undef" and sets $! in case of an error. The limit is one larger
1807 than the highest valid file descriptor number.
1808 IO::AIO::min_fdlimit [$numfd]
1810 Try to increase the current file descriptor limit(s) to at least
1811 $numfd by changing the soft or hard file descriptor resource limit.
1812 If $numfd is missing, it will try to set a very high limit,
1813 although this is not recommended when you know the actual minimum
1814 that you require.
1815 If the limit cannot be raised enough, the function makes a best-
1817 effort attempt to increase the limit as much as possible, using
1818 various tricks, while still failing. You can query the resulting
1819 limit using "IO::AIO::get_fdlimit".
1820 If an error occurs, returns "undef" and sets $!, otherwise returns
1822 true.
1823 IO::AIO::sendfile $ofh, $ifh, $offset, $count
1825 Calls the "eio_sendfile_sync" function, which is like
1826 "aio_sendfile", but is blocking (this makes most sense if you know
1827 the input data is likely cached already and the output filehandle
1828 is set to non-blocking operations).
1829 Returns the number of bytes copied, or "-1" on error.
1831 IO::AIO::fadvise $fh, $offset, $len, $advice
1833 Simply calls the "posix_fadvise" function (see its manpage for
1834 details). The following advice constants are available:
1835 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1836 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1837 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1838 On systems that do not implement "posix_fadvise", this function
1840 returns ENOSYS, otherwise the return value of "posix_fadvise".
1841 IO::AIO::madvise $scalar, $offset, $len, $advice
1843 Simply calls the "posix_madvise" function (see its manpage for
1844 details). The following advice constants are available:
1845 "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1846 "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1847 "IO::AIO::MADV_DONTNEED".
1848 If $offset is negative, counts from the end. If $length is
1850 negative, the remaining length of the $scalar is used. If possible,
1851 $length will be reduced to fit into the $scalar.
1852 On systems that do not implement "posix_madvise", this function
1854 returns ENOSYS, otherwise the return value of "posix_madvise".
1855 IO::AIO::mprotect $scalar, $offset, $len, $protect
1857 Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1858 $scalar (see its manpage for details). The following protect
1859 constants are available: "IO::AIO::PROT_NONE",
1860 "IO::AIO::PROT_READ", "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1861 If $offset is negative, counts from the end. If $length is
1863 negative, the remaining length of the $scalar is used. If possible,
1864 $length will be reduced to fit into the $scalar.
1865 On systems that do not implement "mprotect", this function returns
1867 ENOSYS, otherwise the return value of "mprotect".
1868 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1870 Memory-maps a file (or anonymous memory range) and attaches it to
1871 the given $scalar, which will act like a string scalar. Returns
1872 true on success, and false otherwise.
1873 The scalar must exist, but its contents do not matter - this means
1875 you cannot use a nonexistant array or hash element. When in doubt,
1876 "undef" the scalar first.
1877 The only operations allowed on the mmapped scalar are
1879 "substr"/"vec", which don't change the string length, and most
1880 read-only operations such as copying it or searching it with
1881 regexes and so on.
1882 Anything else is unsafe and will, at best, result in memory leaks.
1884 The memory map associated with the $scalar is automatically removed
1886 when the $scalar is undef'd or destroyed, or when the
1887 "IO::AIO::mmap" or "IO::AIO::munmap" functions are called on it.
1888 This calls the "mmap"(2) function internally. See your system's
1890 manual page for details on the $length, $prot and $flags
1891 parameters.
1892 The $length must be larger than zero and smaller than the actual
1894 filesize.
1895 $prot is a combination of "IO::AIO::PROT_NONE",
1897 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1898 "IO::AIO::PROT_WRITE",
1899 $flags can be a combination of "IO::AIO::MAP_SHARED" or
1901 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1902 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set
1903 to "MAP_ANON" if your system only provides this constant),
1904 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1905 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1906 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1907 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1908 "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1909 "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1910 If $fh is "undef", then a file descriptor of "-1" is passed.
1912 $offset is the offset from the start of the file - it generally
1914 must be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
1915 Example:
1917 use Digest::MD5;
1919 use IO::AIO;
1920 open my $fh, "<verybigfile"
1922 or die "$!";
1923 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
1925 or die "verybigfile: $!";
1926 my $fast_md5 = md5 $data;
1928 IO::AIO::munmap $scalar
1930 Removes a previous mmap and undefines the $scalar.
1931 IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
1933 $new_address = 0]
1934 Calls the Linux-specific mremap(2) system call. The $scalar must
1935 have been mapped by "IO::AIO::mmap", and $flags must currently
1936 either be 0 or "IO::AIO::MREMAP_MAYMOVE".
1937 Returns true if successful, and false otherwise. If the underlying
1939 mmapped region has changed address, then the true value has the
1940 numerical value 1, otherwise it has the numerical value 0:
1941 my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
1943 or die "mremap: $!";
1944 if ($success*1) {
1946 warn "scalar has chanegd address in memory\n";
1947 }
1948 "IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
1950 implemented, but not supported and might go away in a future
1951 version.
1952 On systems where this call is not supported or is not emulated,
1954 this call returns falls and sets $! to "ENOSYS".
1955 IO::AIO::mlockall $flags
1957 Calls the "eio_mlockall_sync" function, which is like
1958 "aio_mlockall", but is blocking.
1959 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1961 Calls the "munlock" function, undoing the effects of a previous
1962 "aio_mlock" call (see its description for details).
1963 IO::AIO::munlockall
1965 Calls the "munlockall" function.
1966 On systems that do not implement "munlockall", this function
1968 returns ENOSYS, otherwise the return value of "munlockall".
1969 $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1971 Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1972 socket and return the new file handle on success, or sets $! and
1973 returns "undef" on error.
1974 The remote name of the new socket will be stored in $sockaddr,
1976 which will be extended to allow for at least $sockaddr_maxlen
1977 octets. If the socket name does not fit into $sockaddr_maxlen
1978 octets, this is signaled by returning a longer string in $sockaddr,
1979 which might or might not be truncated.
1980 To accept name-less sockets, use "undef" for $sockaddr and 0 for
1982 $sockaddr_maxlen.
1983 The main reasons to use this syscall rather than portable accept(2)
1985 are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC"
1986 flags and you can accept name-less sockets by specifying 0 for
1987 $sockaddr_maxlen, which is sadly not possible with perl's interface
1988 to "accept".
1989 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1991 Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
1992 $w_off are "undef", then "NULL" is passed for these, otherwise they
1993 should be the file offset.
1994 $r_fh and $w_fh should not refer to the same file, as splice might
1996 silently corrupt the data in this case.
1997 The following symbol flag values are available:
1999 "IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
2000 "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
2001 See the splice(2) manpage for details.
2003 IO::AIO::tee $r_fh, $w_fh, $length, $flags
2005 Calls the GNU/Linux tee(2) syscall, see its manpage and the
2006 description for "IO::AIO::splice" above for details.
2007 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2009 Attempts to query or change the pipe buffer size. Obviously works
2010 only on pipes, and currently works only on GNU/Linux systems, and
2011 fails with "-1"/"ENOSYS" everywhere else. If anybody knows how to
2012 influence pipe buffer size on other systems, drop me a note.
2013 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
2015 This is a direct interface to the Linux pipe2(2) system call. If
2016 $flags is missing or 0, then this should be the same as a call to
2017 perl's built-in "pipe" function and create a new pipe, and works on
2018 systems that lack the pipe2 syscall. On win32, this case invokes
2019 "_pipe (..., 4096, O_BINARY)".
2020 If $flags is non-zero, it tries to invoke the pipe2 system call
2022 with the given flags (Linux 2.6.27, glibc 2.9).
2023 On success, the read and write file handles are returned.
2025 On error, nothing will be returned. If the pipe2 syscall is missing
2027 and $flags is non-zero, fails with "ENOSYS".
2028 Please refer to pipe2(2) for more info on the $flags, but at the
2030 time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK"
2031 and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were
2032 supported.
2033 Example: create a pipe race-free w.r.t. threads and fork:
2035 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2037 or die "pipe2: $!\n";
2038 $fh = IO::AIO::memfd_create $pathname[, $flags]
2040 This is a direct interface to the Linux memfd_create(2) system
2041 call. The (unhelpful) default for $flags is 0, but your default
2042 should be "IO::AIO::MFD_CLOEXEC".
2043 On success, the new memfd filehandle is returned, otherwise returns
2045 "undef". If the memfd_create syscall is missing, fails with
2046 "ENOSYS".
2047 Please refer to memfd_create(2) for more info on this call.
2049 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
2051 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
2052 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
2053 Example: create a new memfd.
2055 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2057 or die "memfd_create: $!\n";
2058 $fh = IO::AIO::pidfd_open $pid[, $flags]
2060 This is an interface to the Linux pidfd_open(2) system call. The
2061 default for $flags is 0.
2062 On success, a new pidfd filehandle is returned (that is already set
2064 to close-on-exec), otherwise returns "undef". If the syscall is
2065 missing, fails with "ENOSYS".
2066 Example: open pid 6341 as pidfd.
2068 my $fh = IO::AIO::pidfd_open 6341
2070 or die "pidfd_open: $!\n";
2071 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
2073 $flags]]
2074 This is an interface to the Linux pidfd_send_signal system call.
2075 The default for $siginfo is "undef" and the default for $flags is
2076 0.
2077 Returns the system call status. If the syscall is missing, fails
2079 with "ENOSYS".
2080 When specified, $siginfo must be a reference to a hash with one or
2082 more of the following members:
2083 code - the "si_code" member
2085 pid - the "si_pid" member
2086 uid - the "si_uid" member
2087 value_int - the "si_value.sival_int" member
2088 value_ptr - the "si_value.sival_ptr" member, specified as an
2089 integer
2090 Example: send a SIGKILL to the specified process.
2092 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2094 and die "pidfd_send_signal: $!\n";
2095 Example: send a SIGKILL to the specified process with extra data.
2097 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2099 and die "pidfd_send_signal: $!\n";
2100 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2102 This is an interface to the Linux pidfd_getfd system call. The
2103 default for $flags is 0.
2104 On success, returns a dup'ed copy of the target file descriptor
2106 (specified as an integer) returned (that is already set to close-
2107 on-exec), otherwise returns "undef". If the syscall is missing,
2108 fails with "ENOSYS".
2109 Example: get a copy of standard error of another process and print
2111 soemthing to it.
2112 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2114 or die "pidfd_getfd: $!\n";
2115 print $errfh "stderr\n";
2116 $fh = IO::AIO::eventfd [$initval, [$flags]]
2118 This is a direct interface to the Linux eventfd(2) system call. The
2119 (unhelpful) defaults for $initval and $flags are 0 for both.
2120 On success, the new eventfd filehandle is returned, otherwise
2122 returns "undef". If the eventfd syscall is missing, fails with
2123 "ENOSYS".
2124 Please refer to eventfd(2) for more info on this call.
2126 The following symbol flag values are available:
2128 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
2129 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
2130 Example: create a new eventfd filehandle:
2132 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
2134 or die "eventfd: $!\n";
2135 $fh = IO::AIO::timerfd_create $clockid[, $flags]
2137 This is a direct interface to the Linux timerfd_create(2) system
2138 call. The (unhelpful) default for $flags is 0, but your default
2139 should be "IO::AIO::TFD_CLOEXEC".
2140 On success, the new timerfd filehandle is returned, otherwise
2142 returns "undef". If the timerfd_create syscall is missing, fails
2143 with "ENOSYS".
2144 Please refer to timerfd_create(2) for more info on this call.
2146 The following $clockid values are available:
2148 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
2149 "IO::AIO::CLOCK_CLOCK_BOOTTIME" (Linux 3.15)
2150 "IO::AIO::CLOCK_CLOCK_REALTIME_ALARM" (Linux 3.11) and
2151 "IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM" (Linux 3.11).
2152 The following $flags values are available (Linux 2.6.27):
2154 "IO::AIO::TFD_NONBLOCK" and "IO::AIO::TFD_CLOEXEC".
2155 Example: create a new timerfd and set it to one-second repeated
2157 alarms, then wait for two alarms:
2158 my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
2160 or die "timerfd_create: $!\n";
2161 defined IO::AIO::timerfd_settime $fh, 0, 1, 1
2163 or die "timerfd_settime: $!\n";
2164 for (1..2) {
2166 8 == sysread $fh, my $buf, 8
2167 or die "timerfd read failure\n";
2168 printf "number of expirations (likely 1): %d\n",
2170 unpack "Q", $buf;
2171 }
2172 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags,
2174 $new_interval, $nbw_value
2175 This is a direct interface to the Linux timerfd_settime(2) system
2176 call. Please refer to its manpage for more info on this call.
2177 The new itimerspec is specified using two (possibly fractional)
2179 second values, $new_interval and $new_value).
2180 On success, the current interval and value are returned (as per
2182 "timerfd_gettime"). On failure, the empty list is returned.
2183 The following $flags values are available:
2185 "IO::AIO::TFD_TIMER_ABSTIME" and
2186 "IO::AIO::TFD_TIMER_CANCEL_ON_SET".
2187 See "IO::AIO::timerfd_create" for a full example.
2189 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
2191 This is a direct interface to the Linux timerfd_gettime(2) system
2192 call. Please refer to its manpage for more info on this call.
2193 On success, returns the current values of interval and value for
2195 the given timerfd (as potentially fractional second values). On
2196 failure, the empty list is returned.
2197
2199 It is recommended to use AnyEvent::AIO to integrate IO::AIO
2200 automatically into many event loops:
2201 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
2203 use AnyEvent::AIO;
2204 You can also integrate IO::AIO manually into many event loops, here are
2206 some examples of how to do this:
2207 # EV integration
2209 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
2210 # Event integration
2212 Event->io (fd => IO::AIO::poll_fileno,
2213 poll => 'r',
2214 cb => \&IO::AIO::poll_cb);
2215 # Glib/Gtk2 integration
2217 add_watch Glib::IO IO::AIO::poll_fileno,
2218 in => sub { IO::AIO::poll_cb; 1 };
2219 # Tk integration
2221 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
2222 readable => \&IO::AIO::poll_cb);
2223 # Danga::Socket integration
2225 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
2226 \&IO::AIO::poll_cb);
2227 FORK BEHAVIOUR
2229 Usage of pthreads in a program changes the semantics of fork
2230 considerably. Specifically, only async-safe functions can be called
2231 after fork. Perl doesn't know about this, so in general, you cannot
2232 call fork with defined behaviour in perl if pthreads are involved.
2233 IO::AIO uses pthreads, so this applies, but many other extensions and
2234 (for inexplicable reasons) perl itself often is linked against
2235 pthreads, so this limitation applies to quite a lot of perls.
2236 This module no longer tries to fight your OS, or POSIX. That means
2238 IO::AIO only works in the process that loaded it. Forking is fully
2239 supported, but using IO::AIO in the child is not.
2240 You might get around by not using IO::AIO before (or after) forking.
2242 You could also try to call the IO::AIO::reinit function in the child:
2243 IO::AIO::reinit
2245 Abandons all current requests and I/O threads and simply
2246 reinitialises all data structures. This is not an operation
2247 supported by any standards, but happens to work on GNU/Linux and
2248 some newer BSD systems.
2249 The only reasonable use for this function is to call it after
2251 forking, if "IO::AIO" was used in the parent. Calling it while
2252 IO::AIO is active in the process will result in undefined
2253 behaviour. Calling it at any time will also result in any undefined
2254 (by POSIX) behaviour.
2255 LINUX-SPECIFIC CALLS
2257 When a call is documented as "linux-specific" then this means it
2258 originated on GNU/Linux. "IO::AIO" will usually try to autodetect the
2259 availability and compatibility of such calls regardless of the platform
2260 it is compiled on, so platforms such as FreeBSD which often implement
2261 these calls will work. When in doubt, call them and see if they fail
2262 wth "ENOSYS".
2263 MEMORY USAGE
2265 Per-request usage:
2266 Each aio request uses - depending on your architecture - around 100-200
2268 bytes of memory. In addition, stat requests need a stat buffer
2269 (possibly a few hundred bytes), readdir requires a result buffer and so
2270 on. Perl scalars and other data passed into aio requests will also be
2271 locked and will consume memory till the request has entered the done
2272 state.
2273 This is not awfully much, so queuing lots of requests is not usually a
2275 problem.
2276 Per-thread usage:
2278 In the execution phase, some aio requests require more memory for
2280 temporary buffers, and each thread requires a stack and other data
2281 structures (usually around 16k-128k, depending on the OS).
2282
2284 Known bugs will be fixed in the next release :)
2285
2287 Calls that try to "import" foreign memory areas (such as
2288 "IO::AIO::mmap" or "IO::AIO::aio_slurp") do not work with generic
2289 lvalues, such as non-created hash slots or other scalars I didn't think
2290 of. It's best to avoid such and either use scalar variables or making
2291 sure that the scalar exists (e.g. by storing "undef") and isn't "funny"
2292 (e.g. tied).
2293 I am not sure anything can be done about this, so this is considered a
2295 known issue, rather than a bug.
2296
2298 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
2299 more natural syntax and IO::FDPass for file descriptor passing.
2300
2302 Marc Lehmann <schmorp@schmorp.de>
2303 http://home.schmorp.de/
2304perl v5.36.0 2022-09-26 AIO(3)