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, which
286 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 $flags argument is a bitmask. See the "Fcntl" module for a
353 list. They are the same as used by "sysopen".
354 Likewise, $mode specifies the mode of the newly created file, if it
356 didn't exist and "O_CREAT" has been given, just like perl's
357 "sysopen", except that it is mandatory (i.e. use 0 if you don't
358 create new files, and 0666 or 0777 if you do). Note that the $mode
359 will be modified by the umask in effect then the request is being
360 executed, so better never change the umask.
361 Example:
363 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
365 if ($_[0]) {
366 print "open successful, fh is $_[0]\n";
367 ...
368 } else {
369 die "open failed: $!\n";
370 }
371 };
372 In addition to all the common open modes/flags ("O_RDONLY",
374 "O_WRONLY", "O_RDWR", "O_CREAT", "O_TRUNC", "O_EXCL" and
375 "O_APPEND"), the following POSIX and non-POSIX constants are
376 available (missing ones on your system are, as usual, 0):
377 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
379 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
380 "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", "O_TTY_INIT"
381 and "O_ACCMODE".
382 aio_close $fh, $callback->($status)
384 Asynchronously close a file and call the callback with the result
385 code.
386 Unfortunately, you can't do this to perl. Perl insists very
388 strongly on closing the file descriptor associated with the
389 filehandle itself.
390 Therefore, "aio_close" will not close the filehandle - instead it
392 will use dup2 to overwrite the file descriptor with the write-end
393 of a pipe (the pipe fd will be created on demand and will be
394 cached).
395 Or in other words: the file descriptor will be closed, but it will
397 not be free for reuse until the perl filehandle is closed.
398 aio_seek $fh, $offset, $whence, $callback->($offs)
400 Seeks the filehandle to the new $offset, similarly to perl's
401 "sysseek". The $whence can use the traditional values (0 for
402 "IO::AIO::SEEK_SET", 1 for "IO::AIO::SEEK_CUR" or 2 for
403 "IO::AIO::SEEK_END").
404 The resulting absolute offset will be passed to the callback, or -1
406 in case of an error.
407 In theory, the $whence constants could be different than the
409 corresponding values from Fcntl, but perl guarantees they are the
410 same, so don't panic.
411 As a GNU/Linux (and maybe Solaris) extension, also the constants
413 "IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if
414 they could be found. No guarantees about suitability for use in
415 "aio_seek" or Perl's "sysseek" can be made though, although I would
416 naively assume they "just work".
417 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
419 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
420 Reads or writes $length bytes from or to the specified $fh and
421 $offset into the scalar given by $data and offset $dataoffset and
422 calls the callback with the actual number of bytes transferred (or
423 -1 on error, just like the syscall).
424 "aio_read" will, like "sysread", shrink or grow the $data scalar to
426 offset plus the actual number of bytes read.
427 If $offset is undefined, then the current file descriptor offset
429 will be used (and updated), otherwise the file descriptor offset
430 will not be changed by these calls.
431 If $length is undefined in "aio_write", use the remaining length of
433 $data.
434 If $dataoffset is less than zero, it will be counted from the end
436 of $data.
437 The $data scalar MUST NOT be modified in any way while the request
439 is outstanding. Modifying it can result in segfaults or World War
440 III (if the necessary/optional hardware is installed).
441 Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
443 offset 0 within the scalar:
444 aio_read $fh, 7, 15, $buffer, 0, sub {
446 $_[0] > 0 or die "read error: $!";
447 print "read $_[0] bytes: <$buffer>\n";
448 };
449 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
451 Tries to copy $length bytes from $in_fh to $out_fh. It starts
452 reading at byte offset $in_offset, and starts writing at the
453 current file offset of $out_fh. Because of that, it is not safe to
454 issue more than one "aio_sendfile" per $out_fh, as they will
455 interfere with each other. The same $in_fh works fine though, as
456 this function does not move or use the file offset of $in_fh.
457 Please note that "aio_sendfile" can read more bytes from $in_fh
459 than are written, and there is no way to find out how many more
460 bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
461 only provides the number of bytes written to $out_fh. Only if the
462 result value equals $length one can assume that $length bytes have
463 been read.
464 Unlike with other "aio_" functions, it makes a lot of sense to use
466 "aio_sendfile" on non-blocking sockets, as long as one end
467 (typically the $in_fh) is a file - the file I/O will then be
468 asynchronous, while the socket I/O will be non-blocking. Note,
469 however, that you can run into a trap where "aio_sendfile" reads
470 some data with readahead, then fails to write all data, and when
471 the socket is ready the next time, the data in the cache is already
472 lost, forcing "aio_sendfile" to again hit the disk. Explicit
473 "aio_read" + "aio_write" let's you better control resource usage.
474 This call tries to make use of a native "sendfile"-like syscall to
476 provide zero-copy operation. For this to work, $out_fh should refer
477 to a socket, and $in_fh should refer to an mmap'able file.
478 If a native sendfile cannot be found or it fails with "ENOSYS",
480 "EINVAL", "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
481 "ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
482 any type of filehandle regardless of the limitations of the
483 operating system.
484 As native sendfile syscalls (as practically any non-POSIX interface
486 hacked together in a hurry to improve benchmark numbers) tend to be
487 rather buggy on many systems, this implementation tries to work
488 around some known bugs in Linux and FreeBSD kernels (probably
489 others, too), but that might fail, so you really really should
490 check the return value of "aio_sendfile" - fewer bytes than
491 expected might have been transferred.
492 aio_readahead $fh,$offset,$length, $callback->($retval)
494 "aio_readahead" populates the page cache with data from a file so
495 that subsequent reads from that file will not block on disk I/O.
496 The $offset argument specifies the starting point from which data
497 is to be read and $length specifies the number of bytes to be read.
498 I/O is performed in whole pages, so that offset is effectively
499 rounded down to a page boundary and bytes are read up to the next
500 page boundary greater than or equal to (off-set+length).
501 "aio_readahead" does not read beyond the end of the file. The
502 current file offset of the file is left unchanged.
503 If that syscall doesn't exist (likely if your kernel isn't Linux)
505 it will be emulated by simply reading the data, which would have a
506 similar effect.
507 aio_stat $fh_or_path, $callback->($status)
509 aio_lstat $fh, $callback->($status)
510 Works almost exactly like perl's "stat" or "lstat" in void context.
511 The callback will be called after the stat and the results will be
512 available using "stat _" or "-s _" and other tests (with the
513 exception of "-B" and "-T").
514 Currently, the stats are always 64-bit-stats, i.e. instead of
516 returning an error when stat'ing a large file, the results will be
517 silently truncated unless perl itself is compiled with large file
518 support.
519 To help interpret the mode and dev/rdev stat values, IO::AIO offers
521 the following constants and functions (if not implemented, the
522 constants will be 0 and the functions will either "croak" or fall
523 back on traditional behaviour).
524 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
526 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
527 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
528 To access higher resolution stat timestamps, see "SUBSECOND STAT
530 TIME ACCESS".
531 Example: Print the length of /etc/passwd:
533 aio_stat "/etc/passwd", sub {
535 $_[0] and die "stat failed: $!";
536 print "size is ", -s _, "\n";
537 };
538 aio_statvfs $fh_or_path, $callback->($statvfs)
540 Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
541 whether a file handle or path was passed.
542 On success, the callback is passed a hash reference with the
544 following members: "bsize", "frsize", "blocks", "bfree", "bavail",
545 "files", "ffree", "favail", "fsid", "flag" and "namemax". On
546 failure, "undef" is passed.
547 The following POSIX IO::AIO::ST_* constants are defined:
549 "ST_RDONLY" and "ST_NOSUID".
550 The following non-POSIX IO::AIO::ST_* flag masks are defined to
552 their correct value when available, or to 0 on systems that do not
553 support them: "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
554 "ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
555 "ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
556 Example: stat "/wd" and dump out the data if successful.
558 aio_statvfs "/wd", sub {
560 my $f = $_[0]
561 or die "statvfs: $!";
562 use Data::Dumper;
564 say Dumper $f;
565 };
566 # result:
568 {
569 bsize => 1024,
570 bfree => 4333064312,
571 blocks => 10253828096,
572 files => 2050765568,
573 flag => 4096,
574 favail => 2042092649,
575 bavail => 4333064312,
576 ffree => 2042092649,
577 namemax => 255,
578 frsize => 1024,
579 fsid => 1810
580 }
581 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
583 Works like perl's "utime" function (including the special case of
584 $atime and $mtime being undef). Fractional times are supported if
585 the underlying syscalls support them.
586 When called with a pathname, uses utimensat(2) or utimes(2) if
588 available, otherwise utime(2). If called on a file descriptor, uses
589 futimens(2) or futimes(2) if available, otherwise returns ENOSYS,
590 so this is not portable.
591 Examples:
593 # set atime and mtime to current time (basically touch(1)):
595 aio_utime "path", undef, undef;
596 # set atime to current time and mtime to beginning of the epoch:
597 aio_utime "path", time, undef; # undef==0
598 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
600 Works like perl's "chown" function, except that "undef" for either
601 $uid or $gid is being interpreted as "do not change" (but -1 can
602 also be used).
603 Examples:
605 # same as "chown root path" in the shell:
607 aio_chown "path", 0, -1;
608 # same as above:
609 aio_chown "path", 0, undef;
610 aio_truncate $fh_or_path, $offset, $callback->($status)
612 Works like truncate(2) or ftruncate(2).
613 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
615 Allocates or frees disk space according to the $mode argument. See
616 the linux "fallocate" documentation for details.
617 $mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
619 space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
620 IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
621 IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
623 (without leaving a hole), "FALLOC_FL_ZERO_RANGE", to zero a range,
624 "FALLOC_FL_INSERT_RANGE" to insert a range and
625 "FALLOC_FL_UNSHARE_RANGE" to unshare shared blocks (see your
626 fallocate(2) manpage).
627 The file system block size used by "fallocate" is presumably the
629 "f_bsize" returned by "statvfs", but different filesystems and
630 filetypes can dictate other limitations.
631 If "fallocate" isn't available or cannot be emulated (currently no
633 emulation will be attempted), passes -1 and sets $! to "ENOSYS".
634 aio_chmod $fh_or_path, $mode, $callback->($status)
636 Works like perl's "chmod" function.
637 aio_unlink $pathname, $callback->($status)
639 Asynchronously unlink (delete) a file and call the callback with
640 the result code.
641 aio_mknod $pathname, $mode, $dev, $callback->($status)
643 [EXPERIMENTAL]
644 Asynchronously create a device node (or fifo). See mknod(2).
646 The only (POSIX-) portable way of calling this function is:
648 aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
650 See "aio_stat" for info about some potentially helpful extra
652 constants and functions.
653 aio_link $srcpath, $dstpath, $callback->($status)
655 Asynchronously create a new link to the existing object at $srcpath
656 at the path $dstpath and call the callback with the result code.
657 aio_symlink $srcpath, $dstpath, $callback->($status)
659 Asynchronously create a new symbolic link to the existing object at
660 $srcpath at the path $dstpath and call the callback with the result
661 code.
662 aio_readlink $pathname, $callback->($link)
664 Asynchronously read the symlink specified by $path and pass it to
665 the callback. If an error occurs, nothing or undef gets passed to
666 the callback.
667 aio_realpath $pathname, $callback->($path)
669 Asynchronously make the path absolute and resolve any symlinks in
670 $path. The resulting path only consists of directories (same as
671 Cwd::realpath).
672 This request can be used to get the absolute path of the current
674 working directory by passing it a path of . (a single dot).
675 aio_rename $srcpath, $dstpath, $callback->($status)
677 Asynchronously rename the object at $srcpath to $dstpath, just as
678 rename(2) and call the callback with the result code.
679 On systems that support the AIO::WD working directory abstraction
681 natively, the case "[$wd, "."]" as $srcpath is specialcased -
682 instead of failing, "rename" is called on the absolute path of $wd.
683 aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
685 Basically a version of "aio_rename" with an additional $flags
686 argument. Calling this with "$flags=0" is the same as calling
687 "aio_rename".
688 Non-zero flags are currently only supported on GNU/Linux systems
690 that support renameat2. Other systems fail with "ENOSYS" in this
691 case.
692 The following constants are available (missing ones are, as usual
694 0), see renameat2(2) for details:
695 "IO::AIO::RENAME_NOREPLACE", "IO::AIO::RENAME_EXCHANGE" and
697 "IO::AIO::RENAME_WHITEOUT".
698 aio_mkdir $pathname, $mode, $callback->($status)
700 Asynchronously mkdir (create) a directory and call the callback
701 with the result code. $mode will be modified by the umask at the
702 time the request is executed, so do not change your umask.
703 aio_rmdir $pathname, $callback->($status)
705 Asynchronously rmdir (delete) a directory and call the callback
706 with the result code.
707 On systems that support the AIO::WD working directory abstraction
709 natively, the case "[$wd, "."]" is specialcased - instead of
710 failing, "rmdir" is called on the absolute path of $wd.
711 aio_readdir $pathname, $callback->($entries)
713 Unlike the POSIX call of the same name, "aio_readdir" reads an
714 entire directory (i.e. opendir + readdir + closedir). The entries
715 will not be sorted, and will NOT include the "." and ".." entries.
716 The callback is passed a single argument which is either "undef" or
718 an array-ref with the filenames.
719 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
721 Quite similar to "aio_readdir", but the $flags argument allows one
722 to tune behaviour and output format. In case of an error, $entries
723 will be "undef".
724 The flags are a combination of the following constants, ORed
726 together (the flags will also be passed to the callback, possibly
727 modified):
728 IO::AIO::READDIR_DENTS
730 Normally the callback gets an arrayref consisting of names only
731 (as with "aio_readdir"). If this flag is set, then the callback
732 gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
733 describing a single directory entry in more detail:
734 $name is the name of the entry.
736 $type is one of the "IO::AIO::DT_xxx" constants:
738 "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
740 "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
741 "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
742 "IO::AIO::DT_UNKNOWN" means just that: readdir does not know.
744 If you need to know, you have to run stat yourself. Also, for
745 speed/memory reasons, the $type scalars are read-only: you must
746 not modify them.
747 $inode is the inode number (which might not be exact on systems
749 with 64 bit inode numbers and 32 bit perls). This field has
750 unspecified content on systems that do not deliver the inode
751 information.
752 IO::AIO::READDIR_DIRS_FIRST
754 When this flag is set, then the names will be returned in an
755 order where likely directories come first, in optimal stat
756 order. This is useful when you need to quickly find
757 directories, or you want to find all directories while avoiding
758 to stat() each entry.
759 If the system returns type information in readdir, then this is
761 used to find directories directly. Otherwise, likely
762 directories are names beginning with ".", or otherwise names
763 with no dots, of which names with short names are tried first.
764 IO::AIO::READDIR_STAT_ORDER
766 When this flag is set, then the names will be returned in an
767 order suitable for stat()'ing each one. That is, when you plan
768 to stat() most or all files in the given directory, then the
769 returned order will likely be faster.
770 If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
772 specified, then the likely dirs come first, resulting in a less
773 optimal stat order for stat'ing all entries, but likely a more
774 optimal order for finding subdirectories.
775 IO::AIO::READDIR_FOUND_UNKNOWN
777 This flag should not be set when calling "aio_readdirx".
778 Instead, it is being set by "aio_readdirx", when any of the
779 $type's found were "IO::AIO::DT_UNKNOWN". The absence of this
780 flag therefore indicates that all $type's are known, which can
781 be used to speed up some algorithms.
782 aio_slurp $pathname, $offset, $length, $data, $callback->($status)
784 Opens, reads and closes the given file. The data is put into $data,
785 which is resized as required.
786 If $offset is negative, then it is counted from the end of the
788 file.
789 If $length is zero, then the remaining length of the file is used.
791 Also, in this case, the same limitations to modifying $data apply
792 as when IO::AIO::mmap is used, i.e. it must only be modified in-
793 place with "substr". If the size of the file is known, specifying a
794 non-zero $length results in a performance advantage.
795 This request is similar to the older "aio_load" request, but since
797 it is a single request, it might be more efficient to use.
798 Example: load /etc/passwd into $passwd.
800 my $passwd;
802 aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
803 $_[0] >= 0
804 or die "/etc/passwd: $!\n";
805 printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
807 print $passwd;
808 };
809 IO::AIO::flush;
810 aio_load $pathname, $data, $callback->($status)
812 This is a composite request that tries to fully load the given file
813 into memory. Status is the same as with aio_read.
814 Using "aio_slurp" might be more efficient, as it is a single
816 request.
817 aio_copy $srcpath, $dstpath, $callback->($status)
819 Try to copy the file (directories not supported as either source or
820 destination) from $srcpath to $dstpath and call the callback with a
821 status of 0 (ok) or -1 (error, see $!).
822 Existing destination files will be truncated.
824 This is a composite request that creates the destination file with
826 mode 0200 and copies the contents of the source file into it using
827 "aio_sendfile", followed by restoring atime, mtime, access mode and
828 uid/gid, in that order.
829 If an error occurs, the partial destination file will be unlinked,
831 if possible, except when setting atime, mtime, access mode and
832 uid/gid, where errors are being ignored.
833 aio_move $srcpath, $dstpath, $callback->($status)
835 Try to move the file (directories not supported as either source or
836 destination) from $srcpath to $dstpath and call the callback with a
837 status of 0 (ok) or -1 (error, see $!).
838 This is a composite request that tries to rename(2) the file first;
840 if rename fails with "EXDEV", it copies the file with "aio_copy"
841 and, if that is successful, unlinks the $srcpath.
842 aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
844 Scans a directory (similar to "aio_readdir") but additionally tries
845 to efficiently separate the entries of directory $path into two
846 sets of names, directories you can recurse into (directories), and
847 ones you cannot recurse into (everything else, including symlinks
848 to directories).
849 "aio_scandir" is a composite request that generates many sub
851 requests. $maxreq specifies the maximum number of outstanding aio
852 requests that this function generates. If it is "<= 0", then a
853 suitable default will be chosen (currently 4).
854 On error, the callback is called without arguments, otherwise it
856 receives two array-refs with path-relative entry names.
857 Example:
859 aio_scandir $dir, 0, sub {
861 my ($dirs, $nondirs) = @_;
862 print "real directories: @$dirs\n";
863 print "everything else: @$nondirs\n";
864 };
865 Implementation notes.
867 The "aio_readdir" cannot be avoided, but stat()'ing every entry
869 can.
870 If readdir returns file type information, then this is used
872 directly to find directories.
873 Otherwise, after reading the directory, the modification time, size
875 etc. of the directory before and after the readdir is checked, and
876 if they match (and isn't the current time), the link count will be
877 used to decide how many entries are directories (if >= 2).
878 Otherwise, no knowledge of the number of subdirectories will be
879 assumed.
880 Then entries will be sorted into likely directories a non-initial
882 dot currently) and likely non-directories (see "aio_readdirx").
883 Then every entry plus an appended "/." will be "stat"'ed, likely
884 directories first, in order of their inode numbers. If that
885 succeeds, it assumes that the entry is a directory or a symlink to
886 directory (which will be checked separately). This is often faster
887 than stat'ing the entry itself because filesystems might detect the
888 type of the entry without reading the inode data (e.g. ext2fs
889 filetype feature), even on systems that cannot return the filetype
890 information on readdir.
891 If the known number of directories (link count - 2) has been
893 reached, the rest of the entries is assumed to be non-directories.
894 This only works with certainty on POSIX (= UNIX) filesystems, which
896 fortunately are the vast majority of filesystems around.
897 It will also likely work on non-POSIX filesystems with reduced
899 efficiency as those tend to return 0 or 1 as link counts, which
900 disables the directory counting heuristic.
901 aio_rmtree $pathname, $callback->($status)
903 Delete a directory tree starting (and including) $path, return the
904 status of the final "rmdir" only. This is a composite request that
905 uses "aio_scandir" to recurse into and rmdir directories, and
906 unlink everything else.
907 aio_fcntl $fh, $cmd, $arg, $callback->($status)
909 aio_ioctl $fh, $request, $buf, $callback->($status)
910 These work just like the "fcntl" and "ioctl" built-in functions,
911 except they execute asynchronously and pass the return value to the
912 callback.
913 Both calls can be used for a lot of things, some of which make more
915 sense to run asynchronously in their own thread, while some others
916 make less sense. For example, calls that block waiting for external
917 events, such as locking, will also lock down an I/O thread while it
918 is waiting, which can deadlock the whole I/O system. At the same
919 time, there might be no alternative to using a thread to wait.
920 So in general, you should only use these calls for things that do
922 (filesystem) I/O, not for things that wait for other events
923 (network, other processes), although if you are careful and know
924 what you are doing, you still can.
925 The following constants are available and can be used for normal
927 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
928 "F_DUPFD_CLOEXEC",
930 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
932 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
934 "FIDEDUPERANGE".
935 "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
937 "F_SEAL_GROW" and "F_SEAL_WRITE".
938 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
940 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
941 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
943 "FS_IOC_SET_ENCRYPTION_POLICY", "FS_IOC_GET_ENCRYPTION_PWSALT",
944 "FS_IOC_GET_ENCRYPTION_POLICY", "FS_KEY_DESCRIPTOR_SIZE".
945 "FS_SECRM_FL", "FS_UNRM_FL", "FS_COMPR_FL", "FS_SYNC_FL",
947 "FS_IMMUTABLE_FL", "FS_APPEND_FL", "FS_NODUMP_FL", "FS_NOATIME_FL",
948 "FS_DIRTY_FL", "FS_COMPRBLK_FL", "FS_NOCOMP_FL", "FS_ENCRYPT_FL",
949 "FS_BTREE_FL", "FS_INDEX_FL", "FS_JOURNAL_DATA_FL", "FS_NOTAIL_FL",
950 "FS_DIRSYNC_FL", "FS_TOPDIR_FL", "FS_FL_USER_MODIFIABLE".
951 "FS_XFLAG_REALTIME", "FS_XFLAG_PREALLOC", "FS_XFLAG_IMMUTABLE",
953 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
954 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
955 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
956 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
957 "FS_XFLAG_HASATTR",
958 "BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
960 "BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
961 "BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET",
962 "BLKGETSIZE64",
963 aio_sync $callback->($status)
965 Asynchronously call sync and call the callback when finished.
966 aio_fsync $fh, $callback->($status)
968 Asynchronously call fsync on the given filehandle and call the
969 callback with the fsync result code.
970 aio_fdatasync $fh, $callback->($status)
972 Asynchronously call fdatasync on the given filehandle and call the
973 callback with the fdatasync result code.
974 If this call isn't available because your OS lacks it or it
976 couldn't be detected, it will be emulated by calling "fsync"
977 instead.
978 aio_syncfs $fh, $callback->($status)
980 Asynchronously call the syncfs syscall to sync the filesystem
981 associated to the given filehandle and call the callback with the
982 syncfs result code. If syncfs is not available, calls sync(), but
983 returns -1 and sets errno to "ENOSYS" nevertheless.
984 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
986 Sync the data portion of the file specified by $offset and $length
987 to disk (but NOT the metadata), by calling the Linux-specific
988 sync_file_range call. If sync_file_range is not available or it
989 returns ENOSYS, then fdatasync or fsync is being substituted.
990 $flags can be a combination of
992 "IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
993 "IO::AIO::SYNC_FILE_RANGE_WRITE" and
994 "IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
995 manpage for details.
996 aio_pathsync $pathname, $callback->($status)
998 This request tries to open, fsync and close the given path. This is
999 a composite request intended to sync directories after directory
1000 operations (E.g. rename). This might not work on all operating
1001 systems or have any specific effect, but usually it makes sure that
1002 directory changes get written to disc. It works for anything that
1003 can be opened for read-only, not just directories.
1004 Future versions of this function might fall back to other methods
1006 when "fsync" on the directory fails (such as calling "sync").
1007 Passes 0 when everything went ok, and -1 on error.
1009 aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC,
1011 $callback->($status)
1012 This is a rather advanced IO::AIO call, which only works on
1013 mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
1014 also works on data scalars managed by the Sys::Mmap or Mmap
1015 modules, note that the scalar must only be modified in-place while
1016 an aio operation is pending on it).
1017 It calls the "msync" function of your OS, if available, with the
1019 memory area starting at $offset in the string and ending $length
1020 bytes later. If $length is negative, counts from the end, and if
1021 $length is "undef", then it goes till the end of the string. The
1022 flags can be either "IO::AIO::MS_ASYNC" or "IO::AIO::MS_SYNC", plus
1023 an optional "IO::AIO::MS_INVALIDATE".
1024 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
1026 $callback->($status)
1027 This is a rather advanced IO::AIO call, which works best on
1028 mmap(2)ed scalars.
1029 It touches (reads or writes) all memory pages in the specified
1031 range inside the scalar. All caveats and parameters are the same as
1032 for "aio_msync", above, except for flags, which must be either 0
1033 (which reads all pages and ensures they are instantiated) or
1034 "IO::AIO::MT_MODIFY", which modifies the memory pages (by reading
1035 and writing an octet from it, which dirties the page).
1036 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
1038 This is a rather advanced IO::AIO call, which works best on
1039 mmap(2)ed scalars.
1040 It reads in all the pages of the underlying storage into memory (if
1042 any) and locks them, so they are not getting swapped/paged out or
1043 removed.
1044 If $length is undefined, then the scalar will be locked till the
1046 end.
1047 On systems that do not implement "mlock", this function returns -1
1049 and sets errno to "ENOSYS".
1050 Note that the corresponding "munlock" is synchronous and is
1052 documented under "MISCELLANEOUS FUNCTIONS".
1053 Example: open a file, mmap and mlock it - both will be undone when
1055 $data gets destroyed.
1056 open my $fh, "<", $path or die "$path: $!";
1058 my $data;
1059 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1060 aio_mlock $data; # mlock in background
1061 aio_mlockall $flags, $callback->($status)
1063 Calls the "mlockall" function with the given $flags (a combination
1064 of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
1065 "IO::AIO::MCL_ONFAULT").
1066 On systems that do not implement "mlockall", this function returns
1068 -1 and sets errno to "ENOSYS". Similarly, flag combinations not
1069 supported by the system result in a return value of -1 with errno
1070 being set to "EINVAL".
1071 Note that the corresponding "munlockall" is synchronous and is
1073 documented under "MISCELLANEOUS FUNCTIONS".
1074 Example: asynchronously lock all current and future pages into
1076 memory.
1077 aio_mlockall IO::AIO::MCL_FUTURE;
1079 aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
1081 Queries the extents of the given file (by calling the Linux
1082 "FIEMAP" ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt>
1083 for details). If the ioctl is not available on your OS, then this
1084 request will fail with "ENOSYS".
1085 $start is the starting offset to query extents for, $length is the
1087 size of the range to query - if it is "undef", then the whole file
1088 will be queried.
1089 $flags is a combination of flags ("IO::AIO::FIEMAP_FLAG_SYNC" or
1091 "IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
1092 also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
1093 query the data portion.
1094 $count is the maximum number of extent records to return. If it is
1096 "undef", then IO::AIO queries all extents of the range. As a very
1097 special case, if it is 0, then the callback receives the number of
1098 extents instead of the extents themselves (which is unreliable, see
1099 below).
1100 If an error occurs, the callback receives no arguments. The special
1102 "errno" value "IO::AIO::EBADR" is available to test for flag
1103 errors.
1104 Otherwise, the callback receives an array reference with extent
1106 structures. Each extent structure is an array reference itself,
1107 with the following members:
1108 [$logical, $physical, $length, $flags]
1110 Flags is any combination of the following flag values (typically
1112 either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
1113 "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
1115 "IO::AIO::FIEMAP_EXTENT_DELALLOC",
1116 "IO::AIO::FIEMAP_EXTENT_ENCODED",
1117 "IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
1118 "IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
1119 "IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
1120 "IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
1121 "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
1122 or "IO::AIO::FIEMAP_EXTENT_SHARED".
1123 At the time of this writing (Linux 3.2), this request is unreliable
1125 unless $count is "undef", as the kernel has all sorts of bugs
1126 preventing it to return all extents of a range for files with a
1127 large number of extents. The code (only) works around all these
1128 issues if $count is "undef".
1129 aio_group $callback->(...)
1131 This is a very special aio request: Instead of doing something, it
1132 is a container for other aio requests, which is useful if you want
1133 to bundle many requests into a single, composite, request with a
1134 definite callback and the ability to cancel the whole request with
1135 its subrequests.
1136 Returns an object of class IO::AIO::GRP. See its documentation
1138 below for more info.
1139 Example:
1141 my $grp = aio_group sub {
1143 print "all stats done\n";
1144 };
1145 add $grp
1147 (aio_stat ...),
1148 (aio_stat ...),
1149 ...;
1150 aio_nop $callback->()
1152 This is a special request - it does nothing in itself and is only
1153 used for side effects, such as when you want to add a dummy request
1154 to a group so that finishing the requests in the group depends on
1155 executing the given code.
1156 While this request does nothing, it still goes through the
1158 execution phase and still requires a worker thread. Thus, the
1159 callback will not be executed immediately but only after other
1160 requests in the queue have entered their execution phase. This can
1161 be used to measure request latency.
1162 IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED*
1164 Mainly used for debugging and benchmarking, this aio request puts
1165 one of the request workers to sleep for the given time.
1166 While it is theoretically handy to have simple I/O scheduling
1168 requests like sleep and file handle readable/writable, the overhead
1169 this creates is immense (it blocks a thread for a long time) so do
1170 not use this function except to put your application under
1171 artificial I/O pressure.
1172 IO::AIO::WD - multiple working directories
1174 Your process only has one current working directory, which is used by
1175 all threads. This makes it hard to use relative paths (some other
1176 component could call "chdir" at any time, and it is hard to control
1177 when the path will be used by IO::AIO).
1178 One solution for this is to always use absolute paths. This usually
1180 works, but can be quite slow (the kernel has to walk the whole path on
1181 every access), and can also be a hassle to implement.
1182 Newer POSIX systems have a number of functions (openat, fdopendir,
1184 futimensat and so on) that make it possible to specify working
1185 directories per operation.
1186 For portability, and because the clowns who "designed", or shall I
1188 write, perpetrated this new interface were obviously half-drunk, this
1189 abstraction cannot be perfect, though.
1190 IO::AIO allows you to convert directory paths into a so-called
1192 IO::AIO::WD object. This object stores the canonicalised, absolute
1193 version of the path, and on systems that allow it, also a directory
1194 file descriptor.
1195 Everywhere where a pathname is accepted by IO::AIO (e.g. in "aio_stat"
1197 or "aio_unlink"), one can specify an array reference with an
1198 IO::AIO::WD object and a pathname instead (or the IO::AIO::WD object
1199 alone, which gets interpreted as "[$wd, "."]"). If the pathname is
1200 absolute, the IO::AIO::WD object is ignored, otherwise the pathname is
1201 resolved relative to that IO::AIO::WD object.
1202 For example, to get a wd object for /etc and then stat passwd inside,
1204 you would write:
1205 aio_wd "/etc", sub {
1207 my $etcdir = shift;
1208 # although $etcdir can be undef on error, there is generally no reason
1210 # to check for errors here, as aio_stat will fail with ENOENT
1211 # when $etcdir is undef.
1212 aio_stat [$etcdir, "passwd"], sub {
1214 # yay
1215 };
1216 };
1217 The fact that "aio_wd" is a request and not a normal function shows
1219 that creating an IO::AIO::WD object is itself a potentially blocking
1220 operation, which is why it is done asynchronously.
1221 To stat the directory obtained with "aio_wd" above, one could write
1223 either of the following three request calls:
1224 aio_lstat "/etc" , sub { ... # pathname as normal string
1226 aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
1227 aio_lstat $wd , sub { ... # shorthand for the previous
1228 As with normal pathnames, IO::AIO keeps a copy of the working directory
1230 object and the pathname string, so you could write the following
1231 without causing any issues due to $path getting reused:
1232 my $path = [$wd, undef];
1234 for my $name (qw(abc def ghi)) {
1236 $path->[1] = $name;
1237 aio_stat $path, sub {
1238 # ...
1239 };
1240 }
1241 There are some caveats: when directories get renamed (or deleted), the
1243 pathname string doesn't change, so will point to the new directory (or
1244 nowhere at all), while the directory fd, if available on the system,
1245 will still point to the original directory. Most functions accepting a
1246 pathname will use the directory fd on newer systems, and the string on
1247 older systems. Some functions (such as "aio_realpath") will always rely
1248 on the string form of the pathname.
1249 So this functionality is mainly useful to get some protection against
1251 "chdir", to easily get an absolute path out of a relative path for
1252 future reference, and to speed up doing many operations in the same
1253 directory (e.g. when stat'ing all files in a directory).
1254 The following functions implement this working directory abstraction:
1256 aio_wd $pathname, $callback->($wd)
1258 Asynchonously canonicalise the given pathname and convert it to an
1259 IO::AIO::WD object representing it. If possible and supported on
1260 the system, also open a directory fd to speed up pathname
1261 resolution relative to this working directory.
1262 If something goes wrong, then "undef" is passwd to the callback
1264 instead of a working directory object and $! is set appropriately.
1265 Since passing "undef" as working directory component of a pathname
1266 fails the request with "ENOENT", there is often no need for error
1267 checking in the "aio_wd" callback, as future requests using the
1268 value will fail in the expected way.
1269 IO::AIO::CWD
1271 This is a compile time constant (object) that represents the
1272 process current working directory.
1273 Specifying this object as working directory object for a pathname
1275 is as if the pathname would be specified directly, without a
1276 directory object. For example, these calls are functionally
1277 identical:
1278 aio_stat "somefile", sub { ... };
1280 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1281 To recover the path associated with an IO::AIO::WD object, you can use
1283 "aio_realpath":
1284 aio_realpath $wd, sub {
1286 warn "path is $_[0]\n";
1287 };
1288 Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir"
1290 sometimes, fall back to using an absolue path.
1291 IO::AIO::REQ CLASS
1293 All non-aggregate "aio_*" functions return an object of this class when
1294 called in non-void context.
1295 cancel $req
1297 Cancels the request, if possible. Has the effect of skipping
1298 execution when entering the execute state and skipping calling the
1299 callback when entering the the result state, but will leave the
1300 request otherwise untouched (with the exception of readdir). That
1301 means that requests that currently execute will not be stopped and
1302 resources held by the request will not be freed prematurely.
1303 cb $req $callback->(...)
1305 Replace (or simply set) the callback registered to the request.
1306 IO::AIO::GRP CLASS
1308 This class is a subclass of IO::AIO::REQ, so all its methods apply to
1309 objects of this class, too.
1310 A IO::AIO::GRP object is a special request that can contain multiple
1312 other aio requests.
1313 You create one by calling the "aio_group" constructing function with a
1315 callback that will be called when all contained requests have entered
1316 the "done" state:
1317 my $grp = aio_group sub {
1319 print "all requests are done\n";
1320 };
1321 You add requests by calling the "add" method with one or more
1323 "IO::AIO::REQ" objects:
1324 $grp->add (aio_unlink "...");
1326 add $grp aio_stat "...", sub {
1328 $_[0] or return $grp->result ("error");
1329 # add another request dynamically, if first succeeded
1331 add $grp aio_open "...", sub {
1332 $grp->result ("ok");
1333 };
1334 };
1335 This makes it very easy to create composite requests (see the source of
1337 "aio_move" for an application) that work and feel like simple requests.
1338 • The IO::AIO::GRP objects will be cleaned up during calls to
1340 "IO::AIO::poll_cb", just like any other request.
1341 • They can be canceled like any other request. Canceling will cancel
1343 not only the request itself, but also all requests it contains.
1344 • They can also can also be added to other IO::AIO::GRP objects.
1346 • You must not add requests to a group from within the group callback
1348 (or any later time).
1349 Their lifetime, simplified, looks like this: when they are empty, they
1351 will finish very quickly. If they contain only requests that are in the
1352 "done" state, they will also finish. Otherwise they will continue to
1353 exist.
1354 That means after creating a group you have some time to add requests
1356 (precisely before the callback has been invoked, which is only done
1357 within the "poll_cb"). And in the callbacks of those requests, you can
1358 add further requests to the group. And only when all those requests
1359 have finished will the the group itself finish.
1360 add $grp ...
1362 $grp->add (...)
1363 Add one or more requests to the group. Any type of IO::AIO::REQ can
1364 be added, including other groups, as long as you do not create
1365 circular dependencies.
1366 Returns all its arguments.
1368 $grp->cancel_subs
1370 Cancel all subrequests and clears any feeder, but not the group
1371 request itself. Useful when you queued a lot of events but got a
1372 result early.
1373 The group request will finish normally (you cannot add requests to
1375 the group).
1376 $grp->result (...)
1378 Set the result value(s) that will be passed to the group callback
1379 when all subrequests have finished and set the groups errno to the
1380 current value of errno (just like calling "errno" without an error
1381 number). By default, no argument will be passed and errno is zero.
1382 $grp->errno ([$errno])
1384 Sets the group errno value to $errno, or the current value of errno
1385 when the argument is missing.
1386 Every aio request has an associated errno value that is restored
1388 when the callback is invoked. This method lets you change this
1389 value from its default (0).
1390 Calling "result" will also set errno, so make sure you either set
1392 $! before the call to "result", or call c<errno> after it.
1393 feed $grp $callback->($grp)
1395 Sets a feeder/generator on this group: every group can have an
1396 attached generator that generates requests if idle. The idea behind
1397 this is that, although you could just queue as many requests as you
1398 want in a group, this might starve other requests for a potentially
1399 long time. For example, "aio_scandir" might generate hundreds of
1400 thousands of "aio_stat" requests, delaying any later requests for a
1401 long time.
1402 To avoid this, and allow incremental generation of requests, you
1404 can instead a group and set a feeder on it that generates those
1405 requests. The feed callback will be called whenever there are few
1406 enough (see "limit", below) requests active in the group itself and
1407 is expected to queue more requests.
1408 The feed callback can queue as many requests as it likes (i.e.
1410 "add" does not impose any limits).
1411 If the feed does not queue more requests when called, it will be
1413 automatically removed from the group.
1414 If the feed limit is 0 when this method is called, it will be set
1416 to 2 automatically.
1417 Example:
1419 # stat all files in @files, but only ever use four aio requests concurrently:
1421 my $grp = aio_group sub { print "finished\n" };
1423 limit $grp 4;
1424 feed $grp sub {
1425 my $file = pop @files
1426 or return;
1427 add $grp aio_stat $file, sub { ... };
1429 };
1430 limit $grp $num
1432 Sets the feeder limit for the group: The feeder will be called
1433 whenever the group contains less than this many requests.
1434 Setting the limit to 0 will pause the feeding process.
1436 The default value for the limit is 0, but note that setting a
1438 feeder automatically bumps it up to 2.
1439 SUPPORT FUNCTIONS
1441 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1442 $fileno = IO::AIO::poll_fileno
1444 Return the request result pipe file descriptor. This filehandle
1445 must be polled for reading by some mechanism outside this module
1446 (e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If
1447 the pipe becomes readable you have to call "poll_cb" to check the
1448 results.
1449 See "poll_cb" for an example.
1451 IO::AIO::poll_cb
1453 Process some requests that have reached the result phase (i.e. they
1454 have been executed but the results are not yet reported). You have
1455 to call this "regularly" to finish outstanding requests.
1456 Returns 0 if all events could be processed (or there were no events
1458 to process), or -1 if it returned earlier for whatever reason.
1459 Returns immediately when no events are outstanding. The amount of
1460 events processed depends on the settings of
1461 "IO::AIO::max_poll_req", "IO::AIO::max_poll_time" and
1462 "IO::AIO::max_outstanding".
1463 If not all requests were processed for whatever reason, the poll
1465 file descriptor will still be ready when "poll_cb" returns, so
1466 normally you don't have to do anything special to have it called
1467 later.
1468 Apart from calling "IO::AIO::poll_cb" when the event filehandle
1470 becomes ready, it can be beneficial to call this function from
1471 loops which submit a lot of requests, to make sure the results get
1472 processed when they become available and not just when the loop is
1473 finished and the event loop takes over again. This function returns
1474 very fast when there are no outstanding requests.
1475 Example: Install an Event watcher that automatically calls
1477 IO::AIO::poll_cb with high priority (more examples can be found in
1478 the SYNOPSIS section, at the top of this document):
1479 Event->io (fd => IO::AIO::poll_fileno,
1481 poll => 'r', async => 1,
1482 cb => \&IO::AIO::poll_cb);
1483 IO::AIO::poll_wait
1485 Wait until either at least one request is in the result phase or no
1486 requests are outstanding anymore.
1487 This is useful if you want to synchronously wait for some requests
1489 to become ready, without actually handling them.
1490 See "nreqs" for an example.
1492 IO::AIO::poll
1494 Waits until some requests have been handled.
1495 Returns the number of requests processed, but is otherwise strictly
1497 equivalent to:
1498 IO::AIO::poll_wait, IO::AIO::poll_cb
1500 IO::AIO::flush
1502 Wait till all outstanding AIO requests have been handled.
1503 Strictly equivalent to:
1505 IO::AIO::poll_wait, IO::AIO::poll_cb
1507 while IO::AIO::nreqs;
1508 This function can be useful at program aborts, to make sure
1510 outstanding I/O has been done ("IO::AIO" uses an "END" block which
1511 already calls this function on normal exits), or when you are
1512 merely using "IO::AIO" for its more advanced functions, rather than
1513 for async I/O, e.g.:
1514 my ($dirs, $nondirs);
1516 IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1517 IO::AIO::flush;
1518 # $dirs, $nondirs are now set
1519 IO::AIO::max_poll_reqs $nreqs
1521 IO::AIO::max_poll_time $seconds
1522 These set the maximum number of requests (default 0, meaning
1523 infinity) that are being processed by "IO::AIO::poll_cb" in one
1524 call, respectively the maximum amount of time (default 0, meaning
1525 infinity) spent in "IO::AIO::poll_cb" to process requests (more
1526 correctly the mininum amount of time "poll_cb" is allowed to use).
1527 Setting "max_poll_time" to a non-zero value creates an overhead of
1529 one syscall per request processed, which is not normally a problem
1530 unless your callbacks are really really fast or your OS is really
1531 really slow (I am not mentioning Solaris here). Using
1532 "max_poll_reqs" incurs no overhead.
1533 Setting these is useful if you want to ensure some level of
1535 interactiveness when perl is not fast enough to process all
1536 requests in time.
1537 For interactive programs, values such as 0.01 to 0.1 should be
1539 fine.
1540 Example: Install an Event watcher that automatically calls
1542 IO::AIO::poll_cb with low priority, to ensure that other parts of
1543 the program get the CPU sometimes even under high AIO load.
1544 # try not to spend much more than 0.1s in poll_cb
1546 IO::AIO::max_poll_time 0.1;
1547 # use a low priority so other tasks have priority
1549 Event->io (fd => IO::AIO::poll_fileno,
1550 poll => 'r', nice => 1,
1551 cb => &IO::AIO::poll_cb);
1552 CONTROLLING THE NUMBER OF THREADS
1554 IO::AIO::min_parallel $nthreads
1556 Set the minimum number of AIO threads to $nthreads. The current
1557 default is 8, which means eight asynchronous operations can execute
1558 concurrently at any one time (the number of outstanding requests,
1559 however, is unlimited).
1560 IO::AIO starts threads only on demand, when an AIO request is
1562 queued and no free thread exists. Please note that queueing up a
1563 hundred requests can create demand for a hundred threads, even if
1564 it turns out that everything is in the cache and could have been
1565 processed faster by a single thread.
1566 It is recommended to keep the number of threads relatively low, as
1568 some Linux kernel versions will scale negatively with the number of
1569 threads (higher parallelity => MUCH higher latency). With current
1570 Linux 2.6 versions, 4-32 threads should be fine.
1571 Under most circumstances you don't need to call this function, as
1573 the module selects a default that is suitable for low to moderate
1574 load.
1575 IO::AIO::max_parallel $nthreads
1577 Sets the maximum number of AIO threads to $nthreads. If more than
1578 the specified number of threads are currently running, this
1579 function kills them. This function blocks until the limit is
1580 reached.
1581 While $nthreads are zero, aio requests get queued but not executed
1583 until the number of threads has been increased again.
1584 This module automatically runs "max_parallel 0" at program end, to
1586 ensure that all threads are killed and that there are no
1587 outstanding requests.
1588 Under normal circumstances you don't need to call this function.
1590 IO::AIO::max_idle $nthreads
1592 Limit the number of threads (default: 4) that are allowed to idle
1593 (i.e., threads that did not get a request to process within the
1594 idle timeout (default: 10 seconds). That means if a thread becomes
1595 idle while $nthreads other threads are also idle, it will free its
1596 resources and exit.
1597 This is useful when you allow a large number of threads (e.g. 100
1599 or 1000) to allow for extremely high load situations, but want to
1600 free resources under normal circumstances (1000 threads can easily
1601 consume 30MB of RAM).
1602 The default is probably ok in most situations, especially if thread
1604 creation is fast. If thread creation is very slow on your system
1605 you might want to use larger values.
1606 IO::AIO::idle_timeout $seconds
1608 Sets the minimum idle timeout (default 10) after which worker
1609 threads are allowed to exit. SEe "IO::AIO::max_idle".
1610 IO::AIO::max_outstanding $maxreqs
1612 Sets the maximum number of outstanding requests to $nreqs. If you
1613 do queue up more than this number of requests, the next call to
1614 "IO::AIO::poll_cb" (and other functions calling "poll_cb", such as
1615 "IO::AIO::flush" or "IO::AIO::poll") will block until the limit is
1616 no longer exceeded.
1617 In other words, this setting does not enforce a queue limit, but
1619 can be used to make poll functions block if the limit is exceeded.
1620 This is a bad function to use in interactive programs because it
1622 blocks, and a bad way to reduce concurrency because it is inexact.
1623 If you need to issue many requests without being able to call a
1624 poll function on demand, it is better to use an "aio_group"
1625 together with a feed callback.
1626 Its main use is in scripts without an event loop - when you want to
1628 stat a lot of files, you can write something like this:
1629 IO::AIO::max_outstanding 32;
1631 for my $path (...) {
1633 aio_stat $path , ...;
1634 IO::AIO::poll_cb;
1635 }
1636 IO::AIO::flush;
1638 The call to "poll_cb" inside the loop will normally return
1640 instantly, allowing the loop to progress, but as soon as more than
1641 32 requests are in-flight, it will block until some requests have
1642 been handled. This keeps the loop from pushing a large number of
1643 "aio_stat" requests onto the queue (which, with many paths to stat,
1644 can use up a lot of memory).
1645 The default value for "max_outstanding" is very large, so there is
1647 no practical limit on the number of outstanding requests.
1648 STATISTICAL INFORMATION
1650 IO::AIO::nreqs
1652 Returns the number of requests currently in the ready, execute or
1653 pending states (i.e. for which their callback has not been invoked
1654 yet).
1655 Example: wait till there are no outstanding requests anymore:
1657 IO::AIO::poll_wait, IO::AIO::poll_cb
1659 while IO::AIO::nreqs;
1660 IO::AIO::nready
1662 Returns the number of requests currently in the ready state (not
1663 yet executed).
1664 IO::AIO::npending
1666 Returns the number of requests currently in the pending state
1667 (executed, but not yet processed by poll_cb).
1668 SUBSECOND STAT TIME ACCESS
1670 Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
1672 generally find access/modification and change times with subsecond time
1673 accuracy of the system supports it, but perl's built-in functions only
1674 return the integer part.
1675 The following functions return the timestamps of the most recent stat
1677 with subsecond precision on most systems and work both after
1678 "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
1679 value is only meaningful after a successful "stat"/"lstat" call, or
1680 during/after a successful "aio_stat"/"aio_lstat" callback.
1681 This is similar to the Time::HiRes "stat" functions, but can return
1683 full resolution without rounding and work with standard perl "stat",
1684 alleviating the need to call the special "Time::HiRes" functions, which
1685 do not act like their perl counterparts.
1686 On operating systems or file systems where subsecond time resolution is
1688 not supported or could not be detected, a fractional part of 0 is
1689 returned, so it is always safe to call these functions.
1690 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
1692 IO::AIO::st_btime
1693 Return the access, modication, change or birth time, respectively,
1694 including fractional part. Due to the limited precision of floating
1695 point, the accuracy on most platforms is only a bit better than
1696 milliseconds for times around now - see the nsec function family,
1697 below, for full accuracy.
1698 File birth time is only available when the OS and perl support it
1700 (on FreeBSD and NetBSD at the time of this writing, although
1701 support is adaptive, so if your OS/perl gains support, IO::AIO can
1702 take advantage of it). On systems where it isn't available, 0 is
1703 currently returned, but this might change to "undef" in a future
1704 version.
1705 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1707 Returns access, modification, change and birth time all in one go,
1708 and maybe more times in the future version.
1709 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
1711 IO::AIO::st_ctimensec, IO::AIO::st_btimensec
1712 Return the fractional access, modifcation, change or birth time, in
1713 nanoseconds, as an integer in the range 0 to 999999999.
1714 Note that no accessors are provided for access, modification and
1716 change times - you need to get those from "stat _" if required
1717 ("int IO::AIO::st_atime" and so on will not generally give you the
1718 correct value).
1719 $seconds = IO::AIO::st_btimesec
1721 The (integral) seconds part of the file birth time, if available.
1722 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1724 Like the functions above, but returns all four times in one go (and
1725 maybe more in future versions).
1726 $counter = IO::AIO::st_gen
1728 Returns the generation counter (in practice this is just a random
1729 number) of the file. This is only available on platforms which have
1730 this member in their "struct stat" (most BSDs at the time of this
1731 writing) and generally only to the root usert. If unsupported, 0 is
1732 returned, but this might change to "undef" in a future version.
1733 Example: print the high resolution modification time of /etc, using
1735 "stat", and "IO::AIO::aio_stat".
1736 if (stat "/etc") {
1738 printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
1739 }
1740 IO::AIO::aio_stat "/etc", sub {
1742 $_[0]
1743 and return;
1744 printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
1746 };
1747 IO::AIO::flush;
1749 Output of the awbove on my system, showing reduced and full accuracy:
1751 stat(/etc) mtime: 1534043702.020808
1753 aio_stat(/etc) mtime: 1534043702.020807792
1754 MISCELLANEOUS FUNCTIONS
1756 IO::AIO implements some functions that are useful when you want to use
1758 some "Advanced I/O" function not available to in Perl, without going
1759 the "Asynchronous I/O" route. Many of these have an asynchronous
1760 "aio_*" counterpart.
1761 $retval = IO::AIO::fexecve $fh, $argv, $envp
1763 A more-or-less direct equivalent to the POSIX "fexecve" functions,
1764 which allows you to specify the program to be executed via a file
1765 descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if
1766 not available.
1767 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
1769 undef
1770 Calls the GNU/Linux mount syscall with the given arguments. All
1771 except $flags are strings, and if $data is "undef", a "NULL" will
1772 be passed.
1773 The following values for $flags are available:
1775 "IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
1777 "IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
1778 "IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
1779 "IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
1780 "IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
1781 "IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
1782 "IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
1783 "IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
1784 "IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
1785 "IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
1786 "IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
1787 "IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
1788 $retval = IO::AIO::umount $path, $flags = 0
1790 Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
1791 "umount" if $flags is 0, otherwqise always tries to call "umount2".
1792 The following $flags are available:
1794 "IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
1796 and "IO::AIO::UMOUNT_NOFOLLOW".
1797 $numfd = IO::AIO::get_fdlimit
1799 Tries to find the current file descriptor limit and returns it, or
1800 "undef" and sets $! in case of an error. The limit is one larger
1801 than the highest valid file descriptor number.
1802 IO::AIO::min_fdlimit [$numfd]
1804 Try to increase the current file descriptor limit(s) to at least
1805 $numfd by changing the soft or hard file descriptor resource limit.
1806 If $numfd is missing, it will try to set a very high limit,
1807 although this is not recommended when you know the actual minimum
1808 that you require.
1809 If the limit cannot be raised enough, the function makes a best-
1811 effort attempt to increase the limit as much as possible, using
1812 various tricks, while still failing. You can query the resulting
1813 limit using "IO::AIO::get_fdlimit".
1814 If an error occurs, returns "undef" and sets $!, otherwise returns
1816 true.
1817 IO::AIO::sendfile $ofh, $ifh, $offset, $count
1819 Calls the "eio_sendfile_sync" function, which is like
1820 "aio_sendfile", but is blocking (this makes most sense if you know
1821 the input data is likely cached already and the output filehandle
1822 is set to non-blocking operations).
1823 Returns the number of bytes copied, or -1 on error.
1825 IO::AIO::fadvise $fh, $offset, $len, $advice
1827 Simply calls the "posix_fadvise" function (see its manpage for
1828 details). The following advice constants are available:
1829 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1830 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1831 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1832 On systems that do not implement "posix_fadvise", this function
1834 returns ENOSYS, otherwise the return value of "posix_fadvise".
1835 IO::AIO::madvise $scalar, $offset, $len, $advice
1837 Simply calls the "posix_madvise" function (see its manpage for
1838 details). The following advice constants are available:
1839 "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1840 "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1841 "IO::AIO::MADV_DONTNEED".
1842 If $offset is negative, counts from the end. If $length is
1844 negative, the remaining length of the $scalar is used. If possible,
1845 $length will be reduced to fit into the $scalar.
1846 On systems that do not implement "posix_madvise", this function
1848 returns ENOSYS, otherwise the return value of "posix_madvise".
1849 IO::AIO::mprotect $scalar, $offset, $len, $protect
1851 Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1852 $scalar (see its manpage for details). The following protect
1853 constants are available: "IO::AIO::PROT_NONE",
1854 "IO::AIO::PROT_READ", "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1855 If $offset is negative, counts from the end. If $length is
1857 negative, the remaining length of the $scalar is used. If possible,
1858 $length will be reduced to fit into the $scalar.
1859 On systems that do not implement "mprotect", this function returns
1861 ENOSYS, otherwise the return value of "mprotect".
1862 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1864 Memory-maps a file (or anonymous memory range) and attaches it to
1865 the given $scalar, which will act like a string scalar. Returns
1866 true on success, and false otherwise.
1867 The scalar must exist, but its contents do not matter - this means
1869 you cannot use a nonexistant array or hash element. When in doubt,
1870 "undef" the scalar first.
1871 The only operations allowed on the mmapped scalar are
1873 "substr"/"vec", which don't change the string length, and most
1874 read-only operations such as copying it or searching it with
1875 regexes and so on.
1876 Anything else is unsafe and will, at best, result in memory leaks.
1878 The memory map associated with the $scalar is automatically removed
1880 when the $scalar is undef'd or destroyed, or when the
1881 "IO::AIO::mmap" or "IO::AIO::munmap" functions are called on it.
1882 This calls the "mmap"(2) function internally. See your system's
1884 manual page for details on the $length, $prot and $flags
1885 parameters.
1886 The $length must be larger than zero and smaller than the actual
1888 filesize.
1889 $prot is a combination of "IO::AIO::PROT_NONE",
1891 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1892 "IO::AIO::PROT_WRITE",
1893 $flags can be a combination of "IO::AIO::MAP_SHARED" or
1895 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1896 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set
1897 to "MAP_ANON" if your system only provides this constant),
1898 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1899 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1900 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1901 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1902 "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1903 "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1904 If $fh is "undef", then a file descriptor of -1 is passed.
1906 $offset is the offset from the start of the file - it generally
1908 must be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
1909 Example:
1911 use Digest::MD5;
1913 use IO::AIO;
1914 open my $fh, "<verybigfile"
1916 or die "$!";
1917 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
1919 or die "verybigfile: $!";
1920 my $fast_md5 = md5 $data;
1922 IO::AIO::munmap $scalar
1924 Removes a previous mmap and undefines the $scalar.
1925 IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
1927 $new_address = 0]
1928 Calls the Linux-specific mremap(2) system call. The $scalar must
1929 have been mapped by "IO::AIO::mmap", and $flags must currently
1930 either be 0 or "IO::AIO::MREMAP_MAYMOVE".
1931 Returns true if successful, and false otherwise. If the underlying
1933 mmapped region has changed address, then the true value has the
1934 numerical value 1, otherwise it has the numerical value 0:
1935 my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
1937 or die "mremap: $!";
1938 if ($success*1) {
1940 warn "scalar has chanegd address in memory\n";
1941 }
1942 "IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
1944 implemented, but not supported and might go away in a future
1945 version.
1946 On systems where this call is not supported or is not emulated,
1948 this call returns falls and sets $! to "ENOSYS".
1949 IO::AIO::mlockall $flags
1951 Calls the "eio_mlockall_sync" function, which is like
1952 "aio_mlockall", but is blocking.
1953 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1955 Calls the "munlock" function, undoing the effects of a previous
1956 "aio_mlock" call (see its description for details).
1957 IO::AIO::munlockall
1959 Calls the "munlockall" function.
1960 On systems that do not implement "munlockall", this function
1962 returns ENOSYS, otherwise the return value of "munlockall".
1963 $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1965 Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1966 socket and return the new file handle on success, or sets $! and
1967 returns "undef" on error.
1968 The remote name of the new socket will be stored in $sockaddr,
1970 which will be extended to allow for at least $sockaddr_maxlen
1971 octets. If the socket name does not fit into $sockaddr_maxlen
1972 octets, this is signaled by returning a longer string in $sockaddr,
1973 which might or might not be truncated.
1974 To accept name-less sockets, use "undef" for $sockaddr and 0 for
1976 $sockaddr_maxlen.
1977 The main reasons to use this syscall rather than portable accept(2)
1979 are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC"
1980 flags and you can accept name-less sockets by specifying 0 for
1981 $sockaddr_maxlen, which is sadly not possible with perl's interface
1982 to "accept".
1983 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1985 Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
1986 $w_off are "undef", then "NULL" is passed for these, otherwise they
1987 should be the file offset.
1988 $r_fh and $w_fh should not refer to the same file, as splice might
1990 silently corrupt the data in this case.
1991 The following symbol flag values are available:
1993 "IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
1994 "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
1995 See the splice(2) manpage for details.
1997 IO::AIO::tee $r_fh, $w_fh, $length, $flags
1999 Calls the GNU/Linux tee(2) syscall, see its manpage and the
2000 description for "IO::AIO::splice" above for details.
2001 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2003 Attempts to query or change the pipe buffer size. Obviously works
2004 only on pipes, and currently works only on GNU/Linux systems, and
2005 fails with -1/"ENOSYS" everywhere else. If anybody knows how to
2006 influence pipe buffer size on other systems, drop me a note.
2007 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
2009 This is a direct interface to the Linux pipe2(2) system call. If
2010 $flags is missing or 0, then this should be the same as a call to
2011 perl's built-in "pipe" function and create a new pipe, and works on
2012 systems that lack the pipe2 syscall. On win32, this case invokes
2013 "_pipe (..., 4096, O_BINARY)".
2014 If $flags is non-zero, it tries to invoke the pipe2 system call
2016 with the given flags (Linux 2.6.27, glibc 2.9).
2017 On success, the read and write file handles are returned.
2019 On error, nothing will be returned. If the pipe2 syscall is missing
2021 and $flags is non-zero, fails with "ENOSYS".
2022 Please refer to pipe2(2) for more info on the $flags, but at the
2024 time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK"
2025 and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were
2026 supported.
2027 Example: create a pipe race-free w.r.t. threads and fork:
2029 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2031 or die "pipe2: $!\n";
2032 $fh = IO::AIO::memfd_create $pathname[, $flags]
2034 This is a direct interface to the Linux memfd_create(2) system
2035 call. The (unhelpful) default for $flags is 0, but your default
2036 should be "IO::AIO::MFD_CLOEXEC".
2037 On success, the new memfd filehandle is returned, otherwise returns
2039 "undef". If the memfd_create syscall is missing, fails with
2040 "ENOSYS".
2041 Please refer to memfd_create(2) for more info on this call.
2043 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
2045 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
2046 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
2047 Example: create a new memfd.
2049 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2051 or die "memfd_create: $!\n";
2052 $fh = IO::AIO::pidfd_open $pid[, $flags]
2054 This is an interface to the Linux pidfd_open(2) system call. The
2055 default for $flags is 0.
2056 On success, a new pidfd filehandle is returned (that is already set
2058 to close-on-exec), otherwise returns "undef". If the syscall is
2059 missing, fails with "ENOSYS".
2060 Example: open pid 6341 as pidfd.
2062 my $fh = IO::AIO::pidfd_open 6341
2064 or die "pidfd_open: $!\n";
2065 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
2067 $flags]]
2068 This is an interface to the Linux pidfd_send_signal system call.
2069 The default for $siginfo is "undef" and the default for $flags is
2070 0.
2071 Returns the system call status. If the syscall is missing, fails
2073 with "ENOSYS".
2074 When specified, $siginfo must be a reference to a hash with one or
2076 more of the following members:
2077 code - the "si_code" member
2079 pid - the "si_pid" member
2080 uid - the "si_uid" member
2081 value_int - the "si_value.sival_int" member
2082 value_ptr - the "si_value.sival_ptr" member, specified as an
2083 integer
2084 Example: send a SIGKILL to the specified process.
2086 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2088 and die "pidfd_send_signal: $!\n";
2089 Example: send a SIGKILL to the specified process with extra data.
2091 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2093 and die "pidfd_send_signal: $!\n";
2094 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2096 This is an interface to the Linux pidfd_getfd system call. The
2097 default for $flags is 0.
2098 On success, returns a dup'ed copy of the target file descriptor
2100 (specified as an integer) returned (that is already set to close-
2101 on-exec), otherwise returns "undef". If the syscall is missing,
2102 fails with "ENOSYS".
2103 Example: get a copy of standard error of another process and print
2105 soemthing to it.
2106 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2108 or die "pidfd_getfd: $!\n";
2109 print $errfh "stderr\n";
2110 $fh = IO::AIO::eventfd [$initval, [$flags]]
2112 This is a direct interface to the Linux eventfd(2) system call. The
2113 (unhelpful) defaults for $initval and $flags are 0 for both.
2114 On success, the new eventfd filehandle is returned, otherwise
2116 returns "undef". If the eventfd syscall is missing, fails with
2117 "ENOSYS".
2118 Please refer to eventfd(2) for more info on this call.
2120 The following symbol flag values are available:
2122 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
2123 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
2124 Example: create a new eventfd filehandle:
2126 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
2128 or die "eventfd: $!\n";
2129 $fh = IO::AIO::timerfd_create $clockid[, $flags]
2131 This is a direct interface to the Linux timerfd_create(2) system
2132 call. The (unhelpful) default for $flags is 0, but your default
2133 should be "IO::AIO::TFD_CLOEXEC".
2134 On success, the new timerfd filehandle is returned, otherwise
2136 returns "undef". If the timerfd_create syscall is missing, fails
2137 with "ENOSYS".
2138 Please refer to timerfd_create(2) for more info on this call.
2140 The following $clockid values are available:
2142 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
2143 "IO::AIO::CLOCK_CLOCK_BOOTTIME" (Linux 3.15)
2144 "IO::AIO::CLOCK_CLOCK_REALTIME_ALARM" (Linux 3.11) and
2145 "IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM" (Linux 3.11).
2146 The following $flags values are available (Linux 2.6.27):
2148 "IO::AIO::TFD_NONBLOCK" and "IO::AIO::TFD_CLOEXEC".
2149 Example: create a new timerfd and set it to one-second repeated
2151 alarms, then wait for two alarms:
2152 my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
2154 or die "timerfd_create: $!\n";
2155 defined IO::AIO::timerfd_settime $fh, 0, 1, 1
2157 or die "timerfd_settime: $!\n";
2158 for (1..2) {
2160 8 == sysread $fh, my $buf, 8
2161 or die "timerfd read failure\n";
2162 printf "number of expirations (likely 1): %d\n",
2164 unpack "Q", $buf;
2165 }
2166 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags,
2168 $new_interval, $nbw_value
2169 This is a direct interface to the Linux timerfd_settime(2) system
2170 call. Please refer to its manpage for more info on this call.
2171 The new itimerspec is specified using two (possibly fractional)
2173 second values, $new_interval and $new_value).
2174 On success, the current interval and value are returned (as per
2176 "timerfd_gettime"). On failure, the empty list is returned.
2177 The following $flags values are available:
2179 "IO::AIO::TFD_TIMER_ABSTIME" and
2180 "IO::AIO::TFD_TIMER_CANCEL_ON_SET".
2181 See "IO::AIO::timerfd_create" for a full example.
2183 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
2185 This is a direct interface to the Linux timerfd_gettime(2) system
2186 call. Please refer to its manpage for more info on this call.
2187 On success, returns the current values of interval and value for
2189 the given timerfd (as potentially fractional second values). On
2190 failure, the empty list is returned.
2191
2193 It is recommended to use AnyEvent::AIO to integrate IO::AIO
2194 automatically into many event loops:
2195 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
2197 use AnyEvent::AIO;
2198 You can also integrate IO::AIO manually into many event loops, here are
2200 some examples of how to do this:
2201 # EV integration
2203 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
2204 # Event integration
2206 Event->io (fd => IO::AIO::poll_fileno,
2207 poll => 'r',
2208 cb => \&IO::AIO::poll_cb);
2209 # Glib/Gtk2 integration
2211 add_watch Glib::IO IO::AIO::poll_fileno,
2212 in => sub { IO::AIO::poll_cb; 1 };
2213 # Tk integration
2215 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
2216 readable => \&IO::AIO::poll_cb);
2217 # Danga::Socket integration
2219 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
2220 \&IO::AIO::poll_cb);
2221 FORK BEHAVIOUR
2223 Usage of pthreads in a program changes the semantics of fork
2224 considerably. Specifically, only async-safe functions can be called
2225 after fork. Perl doesn't know about this, so in general, you cannot
2226 call fork with defined behaviour in perl if pthreads are involved.
2227 IO::AIO uses pthreads, so this applies, but many other extensions and
2228 (for inexplicable reasons) perl itself often is linked against
2229 pthreads, so this limitation applies to quite a lot of perls.
2230 This module no longer tries to fight your OS, or POSIX. That means
2232 IO::AIO only works in the process that loaded it. Forking is fully
2233 supported, but using IO::AIO in the child is not.
2234 You might get around by not using IO::AIO before (or after) forking.
2236 You could also try to call the IO::AIO::reinit function in the child:
2237 IO::AIO::reinit
2239 Abandons all current requests and I/O threads and simply
2240 reinitialises all data structures. This is not an operation
2241 supported by any standards, but happens to work on GNU/Linux and
2242 some newer BSD systems.
2243 The only reasonable use for this function is to call it after
2245 forking, if "IO::AIO" was used in the parent. Calling it while
2246 IO::AIO is active in the process will result in undefined
2247 behaviour. Calling it at any time will also result in any undefined
2248 (by POSIX) behaviour.
2249 LINUX-SPECIFIC CALLS
2251 When a call is documented as "linux-specific" then this means it
2252 originated on GNU/Linux. "IO::AIO" will usually try to autodetect the
2253 availability and compatibility of such calls regardless of the platform
2254 it is compiled on, so platforms such as FreeBSD which often implement
2255 these calls will work. When in doubt, call them and see if they fail
2256 wth "ENOSYS".
2257 MEMORY USAGE
2259 Per-request usage:
2260 Each aio request uses - depending on your architecture - around 100-200
2262 bytes of memory. In addition, stat requests need a stat buffer
2263 (possibly a few hundred bytes), readdir requires a result buffer and so
2264 on. Perl scalars and other data passed into aio requests will also be
2265 locked and will consume memory till the request has entered the done
2266 state.
2267 This is not awfully much, so queuing lots of requests is not usually a
2269 problem.
2270 Per-thread usage:
2272 In the execution phase, some aio requests require more memory for
2274 temporary buffers, and each thread requires a stack and other data
2275 structures (usually around 16k-128k, depending on the OS).
2276
2278 Known bugs will be fixed in the next release :)
2279
2281 Calls that try to "import" foreign memory areas (such as
2282 "IO::AIO::mmap" or "IO::AIO::aio_slurp") do not work with generic
2283 lvalues, such as non-created hash slots or other scalars I didn't think
2284 of. It's best to avoid such and either use scalar variables or making
2285 sure that the scalar exists (e.g. by storing "undef") and isn't "funny"
2286 (e.g. tied).
2287 I am not sure anything can be done about this, so this is considered a
2289 known issue, rather than a bug.
2290
2292 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
2293 more natural syntax and IO::FDPass for file descriptor passing.
2294
2296 Marc Lehmann <schmorp@schmorp.de>
2297 http://home.schmorp.de/
2298perl v5.36.0 2023-04-02 AIO(3)