1AIO(3) User Contributed Perl Documentation AIO(3)
2
6 IO::AIO - Asynchronous 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 Although the module will work in the presence of other (Perl-) threads,
65 it is currently not reentrant in any way, so use appropriate locking
66 yourself, always call "poll_cb" from within the same thread, or never
67 call "poll_cb" (or other "aio_" functions) recursively.
68 EXAMPLE
70 This is a simple example that uses the EV module and loads /etc/passwd
71 asynchronously:
72 use Fcntl;
74 use EV;
75 use IO::AIO;
76 # register the IO::AIO callback with EV
78 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
79 # queue the request to open /etc/passwd
81 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
82 my $fh = shift
83 or die "error while opening: $!";
84 # stat'ing filehandles is generally non-blocking
86 my $size = -s $fh;
87 # queue a request to read the file
89 my $contents;
90 aio_read $fh, 0, $size, $contents, 0, sub {
91 $_[0] == $size
92 or die "short read: $!";
93 close $fh;
95 # file contents now in $contents
97 print $contents;
98 # exit event loop and program
100 EV::unloop;
101 };
102 };
103 # possibly queue up other requests, or open GUI windows,
105 # check for sockets etc. etc.
106 # process events as long as there are some:
108 EV::loop;
109
111 Every "aio_*" function creates a request. which is a C data structure
112 not directly visible to Perl.
113 If called in non-void context, every request function returns a Perl
115 object representing the request. In void context, nothing is returned,
116 which saves a bit of memory.
117 The perl object is a fairly standard ref-to-hash object. The hash
119 contents are not used by IO::AIO so you are free to store anything you
120 like in it.
121 During their existance, aio requests travel through the following
123 states, in order:
124 ready
126 Immediately after a request is created it is put into the ready
127 state, waiting for a thread to execute it.
128 execute
130 A thread has accepted the request for processing and is currently
131 executing it (e.g. blocking in read).
132 pending
134 The request has been executed and is waiting for result processing.
135 While request submission and execution is fully asynchronous,
137 result processing is not and relies on the perl interpreter calling
138 "poll_cb" (or another function with the same effect).
139 result
141 The request results are processed synchronously by "poll_cb".
142 The "poll_cb" function will process all outstanding aio requests by
144 calling their callbacks, freeing memory associated with them and
145 managing any groups they are contained in.
146 done
148 Request has reached the end of its lifetime and holds no resources
149 anymore (except possibly for the Perl object, but its connection to
150 the actual aio request is severed and calling its methods will
151 either do nothing or result in a runtime error).
152
154 QUICK OVERVIEW
155 This section simply lists the prototypes of the most important
156 functions for quick reference. See the following sections for function-
157 by-function documentation.
158 aio_open $pathname, $flags, $mode, $callback->($fh)
160 aio_close $fh, $callback->($status)
161 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
162 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
163 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
164 aio_readahead $fh,$offset,$length, $callback->($retval)
165 aio_stat $fh_or_path, $callback->($status)
166 aio_lstat $fh, $callback->($status)
167 aio_statvfs $fh_or_path, $callback->($statvfs)
168 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
169 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
170 aio_truncate $fh_or_path, $offset, $callback->($status)
171 aio_chmod $fh_or_path, $mode, $callback->($status)
172 aio_unlink $pathname, $callback->($status)
173 aio_mknod $path, $mode, $dev, $callback->($status)
174 aio_link $srcpath, $dstpath, $callback->($status)
175 aio_symlink $srcpath, $dstpath, $callback->($status)
176 aio_readlink $path, $callback->($link)
177 aio_rename $srcpath, $dstpath, $callback->($status)
178 aio_mkdir $pathname, $mode, $callback->($status)
179 aio_rmdir $pathname, $callback->($status)
180 aio_readdir $pathname, $callback->($entries)
181 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
182 IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
183 IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
184 aio_load $path, $data, $callback->($status)
185 aio_copy $srcpath, $dstpath, $callback->($status)
186 aio_move $srcpath, $dstpath, $callback->($status)
187 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
188 aio_rmtree $path, $callback->($status)
189 aio_sync $callback->($status)
190 aio_fsync $fh, $callback->($status)
191 aio_fdatasync $fh, $callback->($status)
192 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
193 aio_pathsync $path, $callback->($status)
194 aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
195 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
196 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
197 aio_mlockall $flags, $callback->($status)
198 aio_group $callback->(...)
199 aio_nop $callback->()
200 $prev_pri = aioreq_pri [$pri]
202 aioreq_nice $pri_adjust
203 IO::AIO::poll_wait
205 IO::AIO::poll_cb
206 IO::AIO::poll
207 IO::AIO::flush
208 IO::AIO::max_poll_reqs $nreqs
209 IO::AIO::max_poll_time $seconds
210 IO::AIO::min_parallel $nthreads
211 IO::AIO::max_parallel $nthreads
212 IO::AIO::max_idle $nthreads
213 IO::AIO::max_outstanding $maxreqs
214 IO::AIO::nreqs
215 IO::AIO::nready
216 IO::AIO::npending
217 IO::AIO::sendfile $ofh, $ifh, $offset, $count
219 IO::AIO::fadvise $fh, $offset, $len, $advice
220 IO::AIO::madvise $scalar, $offset, $length, $advice
221 IO::AIO::mprotect $scalar, $offset, $length, $protect
222 IO::AIO::munlock $scalar, $offset = 0, $length = undef
223 IO::AIO::munlockall
224 AIO REQUEST FUNCTIONS
226 All the "aio_*" calls are more or less thin wrappers around the syscall
227 with the same name (sans "aio_"). The arguments are similar or
228 identical, and they all accept an additional (and optional) $callback
229 argument which must be a code reference. This code reference will get
230 called with the syscall return code (e.g. most syscalls return "-1" on
231 error, unlike perl, which usually delivers "false") as its sole
232 argument after the given syscall has been executed asynchronously.
233 All functions expecting a filehandle keep a copy of the filehandle
235 internally until the request has finished.
236 All functions return request objects of type IO::AIO::REQ that allow
238 further manipulation of those requests while they are in-flight.
239 The pathnames you pass to these routines must be absolute and encoded
241 as octets. The reason for the former is that at the time the request is
242 being executed, the current working directory could have changed.
243 Alternatively, you can make sure that you never change the current
244 working directory anywhere in the program and then use relative paths.
245 To encode pathnames as octets, either make sure you either: a) always
247 pass in filenames you got from outside (command line, readdir etc.)
248 without tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module
249 and encode your pathnames to the locale (or other) encoding in effect
250 in the user environment, d) use Glib::filename_from_unicode on unicode
251 filenames or e) use something else to ensure your scalar has the
252 correct contents.
253 This works, btw. independent of the internal UTF-8 bit, which IO::AIO
255 handles correctly whether it is set or not.
256 $prev_pri = aioreq_pri [$pri]
258 Returns the priority value that would be used for the next request
259 and, if $pri is given, sets the priority for the next aio request.
260 The default priority is 0, the minimum and maximum priorities are
262 "-4" and 4, respectively. Requests with higher priority will be
263 serviced first.
264 The priority will be reset to 0 after each call to one of the
266 "aio_*" functions.
267 Example: open a file with low priority, then read something from it
269 with higher priority so the read request is serviced before other
270 low priority open requests (potentially spamming the cache):
271 aioreq_pri -3;
273 aio_open ..., sub {
274 return unless $_[0];
275 aioreq_pri -2;
277 aio_read $_[0], ..., sub {
278 ...
279 };
280 };
281 aioreq_nice $pri_adjust
283 Similar to "aioreq_pri", but subtracts the given value from the
284 current priority, so the effect is cumulative.
285 aio_open $pathname, $flags, $mode, $callback->($fh)
287 Asynchronously open or create a file and call the callback with a
288 newly created filehandle for the file.
289 The pathname passed to "aio_open" must be absolute. See API NOTES,
291 above, for an explanation.
292 The $flags argument is a bitmask. See the "Fcntl" module for a
294 list. They are the same as used by "sysopen".
295 Likewise, $mode specifies the mode of the newly created file, if it
297 didn't exist and "O_CREAT" has been given, just like perl's
298 "sysopen", except that it is mandatory (i.e. use 0 if you don't
299 create new files, and 0666 or 0777 if you do). Note that the $mode
300 will be modified by the umask in effect then the request is being
301 executed, so better never change the umask.
302 Example:
304 aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
306 if ($_[0]) {
307 print "open successful, fh is $_[0]\n";
308 ...
309 } else {
310 die "open failed: $!\n";
311 }
312 };
313 aio_close $fh, $callback->($status)
315 Asynchronously close a file and call the callback with the result
316 code.
317 Unfortunately, you can't do this to perl. Perl insists very
319 strongly on closing the file descriptor associated with the
320 filehandle itself.
321 Therefore, "aio_close" will not close the filehandle - instead it
323 will use dup2 to overwrite the file descriptor with the write-end
324 of a pipe (the pipe fd will be created on demand and will be
325 cached).
326 Or in other words: the file descriptor will be closed, but it will
328 not be free for reuse until the perl filehandle is closed.
329 aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
331 aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
332 Reads or writes $length bytes from or to the specified $fh and
333 $offset into the scalar given by $data and offset $dataoffset and
334 calls the callback without the actual number of bytes read (or -1
335 on error, just like the syscall).
336 "aio_read" will, like "sysread", shrink or grow the $data scalar to
338 offset plus the actual number of bytes read.
339 If $offset is undefined, then the current file descriptor offset
341 will be used (and updated), otherwise the file descriptor offset
342 will not be changed by these calls.
343 If $length is undefined in "aio_write", use the remaining length of
345 $data.
346 If $dataoffset is less than zero, it will be counted from the end
348 of $data.
349 The $data scalar MUST NOT be modified in any way while the request
351 is outstanding. Modifying it can result in segfaults or World War
352 III (if the necessary/optional hardware is installed).
353 Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
355 offset 0 within the scalar:
356 aio_read $fh, 7, 15, $buffer, 0, sub {
358 $_[0] > 0 or die "read error: $!";
359 print "read $_[0] bytes: <$buffer>\n";
360 };
361 aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
363 Tries to copy $length bytes from $in_fh to $out_fh. It starts
364 reading at byte offset $in_offset, and starts writing at the
365 current file offset of $out_fh. Because of that, it is not safe to
366 issue more than one "aio_sendfile" per $out_fh, as they will
367 interfere with each other.
368 Please note that "aio_sendfile" can read more bytes from $in_fh
370 than are written, and there is no way to find out how many bytes
371 have been read from "aio_sendfile" alone, as "aio_sendfile" only
372 provides the number of bytes written to $out_fh. Only if the result
373 value equals $length one can assume that $length bytes have been
374 read.
375 Unlike with other "aio_" functions, it makes a lot of sense to use
377 "aio_sendfile" on non-blocking sockets, as long as one end
378 (typically the $in_fh) is a file - the file I/O will then be
379 asynchronous, while the socket I/O will be non-blocking. Note,
380 however, that you can run into a trap where "aio_sendfile" reads
381 some data with readahead, then fails to write all data, and when
382 the socket is ready the next time, the data in the cache is already
383 lost, forcing "aio_sendfile" to again hit the disk. Explicit
384 "aio_read" + "aio_write" let's you control resource usage much
385 better.
386 This call tries to make use of a native "sendfile" syscall to
388 provide zero-copy operation. For this to work, $out_fh should refer
389 to a socket, and $in_fh should refer to an mmap'able file.
390 If a native sendfile cannot be found or it fails with "ENOSYS",
392 "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
393 "ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
394 any type of filehandle regardless of the limitations of the
395 operating system.
396 aio_readahead $fh,$offset,$length, $callback->($retval)
398 "aio_readahead" populates the page cache with data from a file so
399 that subsequent reads from that file will not block on disk I/O.
400 The $offset argument specifies the starting point from which data
401 is to be read and $length specifies the number of bytes to be read.
402 I/O is performed in whole pages, so that offset is effectively
403 rounded down to a page boundary and bytes are read up to the next
404 page boundary greater than or equal to (off-set+length).
405 "aio_readahead" does not read beyond the end of the file. The
406 current file offset of the file is left unchanged.
407 If that syscall doesn't exist (likely if your OS isn't Linux) it
409 will be emulated by simply reading the data, which would have a
410 similar effect.
411 aio_stat $fh_or_path, $callback->($status)
413 aio_lstat $fh, $callback->($status)
414 Works like perl's "stat" or "lstat" in void context. The callback
415 will be called after the stat and the results will be available
416 using "stat _" or "-s _" etc...
417 The pathname passed to "aio_stat" must be absolute. See API NOTES,
419 above, for an explanation.
420 Currently, the stats are always 64-bit-stats, i.e. instead of
422 returning an error when stat'ing a large file, the results will be
423 silently truncated unless perl itself is compiled with large file
424 support.
425 Example: Print the length of /etc/passwd:
427 aio_stat "/etc/passwd", sub {
429 $_[0] and die "stat failed: $!";
430 print "size is ", -s _, "\n";
431 };
432 aio_statvfs $fh_or_path, $callback->($statvfs)
434 Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
435 whether a file handle or path was passed.
436 On success, the callback is passed a hash reference with the
438 following members: "bsize", "frsize", "blocks", "bfree", "bavail",
439 "files", "ffree", "favail", "fsid", "flag" and "namemax". On
440 failure, "undef" is passed.
441 The following POSIX IO::AIO::ST_* constants are defined:
443 "ST_RDONLY" and "ST_NOSUID".
444 The following non-POSIX IO::AIO::ST_* flag masks are defined to
446 their correct value when available, or to 0 on systems that do not
447 support them: "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
448 "ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
449 "ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
450 Example: stat "/wd" and dump out the data if successful.
452 aio_statvfs "/wd", sub {
454 my $f = $_[0]
455 or die "statvfs: $!";
456 use Data::Dumper;
458 say Dumper $f;
459 };
460 # result:
462 {
463 bsize => 1024,
464 bfree => 4333064312,
465 blocks => 10253828096,
466 files => 2050765568,
467 flag => 4096,
468 favail => 2042092649,
469 bavail => 4333064312,
470 ffree => 2042092649,
471 namemax => 255,
472 frsize => 1024,
473 fsid => 1810
474 }
475 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
477 Works like perl's "utime" function (including the special case of
478 $atime and $mtime being undef). Fractional times are supported if
479 the underlying syscalls support them.
480 When called with a pathname, uses utimes(2) if available, otherwise
482 utime(2). If called on a file descriptor, uses futimes(2) if
483 available, otherwise returns ENOSYS, so this is not portable.
484 Examples:
486 # set atime and mtime to current time (basically touch(1)):
488 aio_utime "path", undef, undef;
489 # set atime to current time and mtime to beginning of the epoch:
490 aio_utime "path", time, undef; # undef==0
491 aio_chown $fh_or_path, $uid, $gid, $callback->($status)
493 Works like perl's "chown" function, except that "undef" for either
494 $uid or $gid is being interpreted as "do not change" (but -1 can
495 also be used).
496 Examples:
498 # same as "chown root path" in the shell:
500 aio_chown "path", 0, -1;
501 # same as above:
502 aio_chown "path", 0, undef;
503 aio_truncate $fh_or_path, $offset, $callback->($status)
505 Works like truncate(2) or ftruncate(2).
506 aio_chmod $fh_or_path, $mode, $callback->($status)
508 Works like perl's "chmod" function.
509 aio_unlink $pathname, $callback->($status)
511 Asynchronously unlink (delete) a file and call the callback with
512 the result code.
513 aio_mknod $path, $mode, $dev, $callback->($status)
515 [EXPERIMENTAL]
516 Asynchronously create a device node (or fifo). See mknod(2).
518 The only (POSIX-) portable way of calling this function is:
520 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
522 aio_link $srcpath, $dstpath, $callback->($status)
524 Asynchronously create a new link to the existing object at $srcpath
525 at the path $dstpath and call the callback with the result code.
526 aio_symlink $srcpath, $dstpath, $callback->($status)
528 Asynchronously create a new symbolic link to the existing object at
529 $srcpath at the path $dstpath and call the callback with the result
530 code.
531 aio_readlink $path, $callback->($link)
533 Asynchronously read the symlink specified by $path and pass it to
534 the callback. If an error occurs, nothing or undef gets passed to
535 the callback.
536 aio_rename $srcpath, $dstpath, $callback->($status)
538 Asynchronously rename the object at $srcpath to $dstpath, just as
539 rename(2) and call the callback with the result code.
540 aio_mkdir $pathname, $mode, $callback->($status)
542 Asynchronously mkdir (create) a directory and call the callback
543 with the result code. $mode will be modified by the umask at the
544 time the request is executed, so do not change your umask.
545 aio_rmdir $pathname, $callback->($status)
547 Asynchronously rmdir (delete) a directory and call the callback
548 with the result code.
549 aio_readdir $pathname, $callback->($entries)
551 Unlike the POSIX call of the same name, "aio_readdir" reads an
552 entire directory (i.e. opendir + readdir + closedir). The entries
553 will not be sorted, and will NOT include the "." and ".." entries.
554 The callback is passed a single argument which is either "undef" or
556 an array-ref with the filenames.
557 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
559 Quite similar to "aio_readdir", but the $flags argument allows to
560 tune behaviour and output format. In case of an error, $entries
561 will be "undef".
562 The flags are a combination of the following constants, ORed
564 together (the flags will also be passed to the callback, possibly
565 modified):
566 IO::AIO::READDIR_DENTS
568 When this flag is off, then the callback gets an arrayref with
569 of names only (as with "aio_readdir"), otherwise it gets an
570 arrayref with "[$name, $type, $inode]" arrayrefs, each
571 describing a single directory entry in more detail.
572 $name is the name of the entry.
574 $type is one of the "IO::AIO::DT_xxx" constants:
576 "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
578 "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
579 "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
580 "IO::AIO::DT_UNKNOWN" means just that: readdir does not know.
582 If you need to know, you have to run stat yourself. Also, for
583 speed reasons, the $type scalars are read-only: you can not
584 modify them.
585 $inode is the inode number (which might not be exact on systems
587 with 64 bit inode numbers and 32 bit perls). This field has
588 unspecified content on systems that do not deliver the inode
589 information.
590 IO::AIO::READDIR_DIRS_FIRST
592 When this flag is set, then the names will be returned in an
593 order where likely directories come first. This is useful when
594 you need to quickly find directories, or you want to find all
595 directories while avoiding to stat() each entry.
596 If the system returns type information in readdir, then this is
598 used to find directories directly. Otherwise, likely
599 directories are files beginning with ".", or otherwise files
600 with no dots, of which files with short names are tried first.
601 IO::AIO::READDIR_STAT_ORDER
603 When this flag is set, then the names will be returned in an
604 order suitable for stat()'ing each one. That is, when you plan
605 to stat() all files in the given directory, then the returned
606 order will likely be fastest.
607 If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
609 specified, then the likely dirs come first, resulting in a less
610 optimal stat order.
611 IO::AIO::READDIR_FOUND_UNKNOWN
613 This flag should not be set when calling "aio_readdirx".
614 Instead, it is being set by "aio_readdirx", when any of the
615 $type's found were "IO::AIO::DT_UNKNOWN". The absense of this
616 flag therefore indicates that all $type's are known, which can
617 be used to speed up some algorithms.
618 aio_load $path, $data, $callback->($status)
620 This is a composite request that tries to fully load the given file
621 into memory. Status is the same as with aio_read.
622 aio_copy $srcpath, $dstpath, $callback->($status)
624 Try to copy the file (directories not supported as either source or
625 destination) from $srcpath to $dstpath and call the callback with a
626 status of 0 (ok) or "-1" (error, see $!).
627 This is a composite request that creates the destination file with
629 mode 0200 and copies the contents of the source file into it using
630 "aio_sendfile", followed by restoring atime, mtime, access mode and
631 uid/gid, in that order.
632 If an error occurs, the partial destination file will be unlinked,
634 if possible, except when setting atime, mtime, access mode and
635 uid/gid, where errors are being ignored.
636 aio_move $srcpath, $dstpath, $callback->($status)
638 Try to move the file (directories not supported as either source or
639 destination) from $srcpath to $dstpath and call the callback with a
640 status of 0 (ok) or "-1" (error, see $!).
641 This is a composite request that tries to rename(2) the file first;
643 if rename fails with "EXDEV", it copies the file with "aio_copy"
644 and, if that is successful, unlinks the $srcpath.
645 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
647 Scans a directory (similar to "aio_readdir") but additionally tries
648 to efficiently separate the entries of directory $path into two
649 sets of names, directories you can recurse into (directories), and
650 ones you cannot recurse into (everything else, including symlinks
651 to directories).
652 "aio_scandir" is a composite request that creates of many sub
654 requests_ $maxreq specifies the maximum number of outstanding aio
655 requests that this function generates. If it is "<= 0", then a
656 suitable default will be chosen (currently 4).
657 On error, the callback is called without arguments, otherwise it
659 receives two array-refs with path-relative entry names.
660 Example:
662 aio_scandir $dir, 0, sub {
664 my ($dirs, $nondirs) = @_;
665 print "real directories: @$dirs\n";
666 print "everything else: @$nondirs\n";
667 };
668 Implementation notes.
670 The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
672 can.
673 If readdir returns file type information, then this is used
675 directly to find directories.
676 Otherwise, after reading the directory, the modification time, size
678 etc. of the directory before and after the readdir is checked, and
679 if they match (and isn't the current time), the link count will be
680 used to decide how many entries are directories (if >= 2).
681 Otherwise, no knowledge of the number of subdirectories will be
682 assumed.
683 Then entries will be sorted into likely directories a non-initial
685 dot currently) and likely non-directories (see "aio_readdirx").
686 Then every entry plus an appended "/." will be "stat"'ed, likely
687 directories first, in order of their inode numbers. If that
688 succeeds, it assumes that the entry is a directory or a symlink to
689 directory (which will be checked seperately). This is often faster
690 than stat'ing the entry itself because filesystems might detect the
691 type of the entry without reading the inode data (e.g. ext2fs
692 filetype feature), even on systems that cannot return the filetype
693 information on readdir.
694 If the known number of directories (link count - 2) has been
696 reached, the rest of the entries is assumed to be non-directories.
697 This only works with certainty on POSIX (= UNIX) filesystems, which
699 fortunately are the vast majority of filesystems around.
700 It will also likely work on non-POSIX filesystems with reduced
702 efficiency as those tend to return 0 or 1 as link counts, which
703 disables the directory counting heuristic.
704 aio_rmtree $path, $callback->($status)
706 Delete a directory tree starting (and including) $path, return the
707 status of the final "rmdir" only. This is a composite request that
708 uses "aio_scandir" to recurse into and rmdir directories, and
709 unlink everything else.
710 aio_sync $callback->($status)
712 Asynchronously call sync and call the callback when finished.
713 aio_fsync $fh, $callback->($status)
715 Asynchronously call fsync on the given filehandle and call the
716 callback with the fsync result code.
717 aio_fdatasync $fh, $callback->($status)
719 Asynchronously call fdatasync on the given filehandle and call the
720 callback with the fdatasync result code.
721 If this call isn't available because your OS lacks it or it
723 couldn't be detected, it will be emulated by calling "fsync"
724 instead.
725 aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
727 Sync the data portion of the file specified by $offset and $length
728 to disk (but NOT the metadata), by calling the Linux-specific
729 sync_file_range call. If sync_file_range is not available or it
730 returns ENOSYS, then fdatasync or fsync is being substituted.
731 $flags can be a combination of
733 "IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
734 "IO::AIO::SYNC_FILE_RANGE_WRITE" and
735 "IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
736 manpage for details.
737 aio_pathsync $path, $callback->($status)
739 This request tries to open, fsync and close the given path. This is
740 a composite request intended to sync directories after directory
741 operations (E.g. rename). This might not work on all operating
742 systems or have any specific effect, but usually it makes sure that
743 directory changes get written to disc. It works for anything that
744 can be opened for read-only, not just directories.
745 Future versions of this function might fall back to other methods
747 when "fsync" on the directory fails (such as calling "sync").
748 Passes 0 when everything went ok, and "-1" on error.
750 aio_msync $scalar, $offset = 0, $length = undef, flags = 0,
752 $callback->($status)
753 This is a rather advanced IO::AIO call, which only works on
754 mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
755 also works on data scalars managed by the Sys::Mmap or Mmap
756 modules, note that the scalar must only be modified in-place while
757 an aio operation is pending on it).
758 It calls the "msync" function of your OS, if available, with the
760 memory area starting at $offset in the string and ending $length
761 bytes later. If $length is negative, counts from the end, and if
762 $length is "undef", then it goes till the end of the string. The
763 flags can be a combination of "IO::AIO::MS_ASYNC",
764 "IO::AIO::MS_INVALIDATE" and "IO::AIO::MS_SYNC".
765 aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
767 $callback->($status)
768 This is a rather advanced IO::AIO call, which works best on
769 mmap(2)ed scalars.
770 It touches (reads or writes) all memory pages in the specified
772 range inside the scalar. All caveats and parameters are the same
773 as for "aio_msync", above, except for flags, which must be either 0
774 (which reads all pages and ensures they are instantiated) or
775 "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading
776 and writing an octet from it, which dirties the page).
777 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
779 This is a rather advanced IO::AIO call, which works best on
780 mmap(2)ed scalars.
781 It reads in all the pages of the underlying storage into memory (if
783 any) and locks them, so they are not getting swapped/paged out or
784 removed.
785 If $length is undefined, then the scalar will be locked till the
787 end.
788 On systems that do not implement "mlock", this function returns
790 "-1" and sets errno to "ENOSYS".
791 Note that the corresponding "munlock" is synchronous and is
793 documented under "MISCELLANEOUS FUNCTIONS".
794 Example: open a file, mmap and mlock it - both will be undone when
796 $data gets destroyed.
797 open my $fh, "<", $path or die "$path: $!";
799 my $data;
800 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
801 aio_mlock $data; # mlock in background
802 aio_mlockall $flags, $callback->($status)
804 Calls the "mlockall" function with the given $flags (a combination
805 of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
806 On systems that do not implement "mlockall", this function returns
808 "-1" and sets errno to "ENOSYS".
809 Note that the corresponding "munlockall" is synchronous and is
811 documented under "MISCELLANEOUS FUNCTIONS".
812 Example: asynchronously lock all current and future pages into
814 memory.
815 aio_mlockall IO::AIO::MCL_FUTURE;
817 aio_group $callback->(...)
819 This is a very special aio request: Instead of doing something, it
820 is a container for other aio requests, which is useful if you want
821 to bundle many requests into a single, composite, request with a
822 definite callback and the ability to cancel the whole request with
823 its subrequests.
824 Returns an object of class IO::AIO::GRP. See its documentation
826 below for more info.
827 Example:
829 my $grp = aio_group sub {
831 print "all stats done\n";
832 };
833 add $grp
835 (aio_stat ...),
836 (aio_stat ...),
837 ...;
838 aio_nop $callback->()
840 This is a special request - it does nothing in itself and is only
841 used for side effects, such as when you want to add a dummy request
842 to a group so that finishing the requests in the group depends on
843 executing the given code.
844 While this request does nothing, it still goes through the
846 execution phase and still requires a worker thread. Thus, the
847 callback will not be executed immediately but only after other
848 requests in the queue have entered their execution phase. This can
849 be used to measure request latency.
850 IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED*
852 Mainly used for debugging and benchmarking, this aio request puts
853 one of the request workers to sleep for the given time.
854 While it is theoretically handy to have simple I/O scheduling
856 requests like sleep and file handle readable/writable, the overhead
857 this creates is immense (it blocks a thread for a long time) so do
858 not use this function except to put your application under
859 artificial I/O pressure.
860 IO::AIO::REQ CLASS
862 All non-aggregate "aio_*" functions return an object of this class when
863 called in non-void context.
864 cancel $req
866 Cancels the request, if possible. Has the effect of skipping
867 execution when entering the execute state and skipping calling the
868 callback when entering the the result state, but will leave the
869 request otherwise untouched (with the exception of readdir). That
870 means that requests that currently execute will not be stopped and
871 resources held by the request will not be freed prematurely.
872 cb $req $callback->(...)
874 Replace (or simply set) the callback registered to the request.
875 IO::AIO::GRP CLASS
877 This class is a subclass of IO::AIO::REQ, so all its methods apply to
878 objects of this class, too.
879 A IO::AIO::GRP object is a special request that can contain multiple
881 other aio requests.
882 You create one by calling the "aio_group" constructing function with a
884 callback that will be called when all contained requests have entered
885 the "done" state:
886 my $grp = aio_group sub {
888 print "all requests are done\n";
889 };
890 You add requests by calling the "add" method with one or more
892 "IO::AIO::REQ" objects:
893 $grp->add (aio_unlink "...");
895 add $grp aio_stat "...", sub {
897 $_[0] or return $grp->result ("error");
898 # add another request dynamically, if first succeeded
900 add $grp aio_open "...", sub {
901 $grp->result ("ok");
902 };
903 };
904 This makes it very easy to create composite requests (see the source of
906 "aio_move" for an application) that work and feel like simple requests.
907 · The IO::AIO::GRP objects will be cleaned up during calls to
909 "IO::AIO::poll_cb", just like any other request.
910 · They can be canceled like any other request. Canceling will cancel
912 not only the request itself, but also all requests it contains.
913 · They can also can also be added to other IO::AIO::GRP objects.
915 · You must not add requests to a group from within the group callback
917 (or any later time).
918 Their lifetime, simplified, looks like this: when they are empty, they
920 will finish very quickly. If they contain only requests that are in the
921 "done" state, they will also finish. Otherwise they will continue to
922 exist.
923 That means after creating a group you have some time to add requests
925 (precisely before the callback has been invoked, which is only done
926 within the "poll_cb"). And in the callbacks of those requests, you can
927 add further requests to the group. And only when all those requests
928 have finished will the the group itself finish.
929 add $grp ...
931 $grp->add (...)
932 Add one or more requests to the group. Any type of IO::AIO::REQ can
933 be added, including other groups, as long as you do not create
934 circular dependencies.
935 Returns all its arguments.
937 $grp->cancel_subs
939 Cancel all subrequests and clears any feeder, but not the group
940 request itself. Useful when you queued a lot of events but got a
941 result early.
942 The group request will finish normally (you cannot add requests to
944 the group).
945 $grp->result (...)
947 Set the result value(s) that will be passed to the group callback
948 when all subrequests have finished and set the groups errno to the
949 current value of errno (just like calling "errno" without an error
950 number). By default, no argument will be passed and errno is zero.
951 $grp->errno ([$errno])
953 Sets the group errno value to $errno, or the current value of errno
954 when the argument is missing.
955 Every aio request has an associated errno value that is restored
957 when the callback is invoked. This method lets you change this
958 value from its default (0).
959 Calling "result" will also set errno, so make sure you either set
961 $! before the call to "result", or call c<errno> after it.
962 feed $grp $callback->($grp)
964 Sets a feeder/generator on this group: every group can have an
965 attached generator that generates requests if idle. The idea behind
966 this is that, although you could just queue as many requests as you
967 want in a group, this might starve other requests for a potentially
968 long time. For example, "aio_scandir" might generate hundreds of
969 thousands "aio_stat" requests, delaying any later requests for a
970 long time.
971 To avoid this, and allow incremental generation of requests, you
973 can instead a group and set a feeder on it that generates those
974 requests. The feed callback will be called whenever there are few
975 enough (see "limit", below) requests active in the group itself and
976 is expected to queue more requests.
977 The feed callback can queue as many requests as it likes (i.e.
979 "add" does not impose any limits).
980 If the feed does not queue more requests when called, it will be
982 automatically removed from the group.
983 If the feed limit is 0 when this method is called, it will be set
985 to 2 automatically.
986 Example:
988 # stat all files in @files, but only ever use four aio requests concurrently:
990 my $grp = aio_group sub { print "finished\n" };
992 limit $grp 4;
993 feed $grp sub {
994 my $file = pop @files
995 or return;
996 add $grp aio_stat $file, sub { ... };
998 };
999 limit $grp $num
1001 Sets the feeder limit for the group: The feeder will be called
1002 whenever the group contains less than this many requests.
1003 Setting the limit to 0 will pause the feeding process.
1005 The default value for the limit is 0, but note that setting a
1007 feeder automatically bumps it up to 2.
1008 SUPPORT FUNCTIONS
1010 EVENT PROCESSING AND EVENT LOOP INTEGRATION
1011 $fileno = IO::AIO::poll_fileno
1013 Return the request result pipe file descriptor. This filehandle
1014 must be polled for reading by some mechanism outside this module
1015 (e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If
1016 the pipe becomes readable you have to call "poll_cb" to check the
1017 results.
1018 See "poll_cb" for an example.
1020 IO::AIO::poll_cb
1022 Process some outstanding events on the result pipe. You have to
1023 call this regularly. Returns 0 if all events could be processed, or
1024 "-1" if it returned earlier for whatever reason. Returns
1025 immediately when no events are outstanding. The amount of events
1026 processed depends on the settings of "IO::AIO::max_poll_req" and
1027 "IO::AIO::max_poll_time".
1028 If not all requests were processed for whatever reason, the
1030 filehandle will still be ready when "poll_cb" returns, so normally
1031 you don't have to do anything special to have it called later.
1032 Example: Install an Event watcher that automatically calls
1034 IO::AIO::poll_cb with high priority (more examples can be found in
1035 the SYNOPSIS section, at the top of this document):
1036 Event->io (fd => IO::AIO::poll_fileno,
1038 poll => 'r', async => 1,
1039 cb => \&IO::AIO::poll_cb);
1040 IO::AIO::poll_wait
1042 If there are any outstanding requests and none of them in the
1043 result phase, wait till the result filehandle becomes ready for
1044 reading (simply does a "select" on the filehandle. This is useful
1045 if you want to synchronously wait for some requests to finish).
1046 See "nreqs" for an example.
1048 IO::AIO::poll
1050 Waits until some requests have been handled.
1051 Returns the number of requests processed, but is otherwise strictly
1053 equivalent to:
1054 IO::AIO::poll_wait, IO::AIO::poll_cb
1056 IO::AIO::flush
1058 Wait till all outstanding AIO requests have been handled.
1059 Strictly equivalent to:
1061 IO::AIO::poll_wait, IO::AIO::poll_cb
1063 while IO::AIO::nreqs;
1064 IO::AIO::max_poll_reqs $nreqs
1066 IO::AIO::max_poll_time $seconds
1067 These set the maximum number of requests (default 0, meaning
1068 infinity) that are being processed by "IO::AIO::poll_cb" in one
1069 call, respectively the maximum amount of time (default 0, meaning
1070 infinity) spent in "IO::AIO::poll_cb" to process requests (more
1071 correctly the mininum amount of time "poll_cb" is allowed to use).
1072 Setting "max_poll_time" to a non-zero value creates an overhead of
1074 one syscall per request processed, which is not normally a problem
1075 unless your callbacks are really really fast or your OS is really
1076 really slow (I am not mentioning Solaris here). Using
1077 "max_poll_reqs" incurs no overhead.
1078 Setting these is useful if you want to ensure some level of
1080 interactiveness when perl is not fast enough to process all
1081 requests in time.
1082 For interactive programs, values such as 0.01 to 0.1 should be
1084 fine.
1085 Example: Install an Event watcher that automatically calls
1087 IO::AIO::poll_cb with low priority, to ensure that other parts of
1088 the program get the CPU sometimes even under high AIO load.
1089 # try not to spend much more than 0.1s in poll_cb
1091 IO::AIO::max_poll_time 0.1;
1092 # use a low priority so other tasks have priority
1094 Event->io (fd => IO::AIO::poll_fileno,
1095 poll => 'r', nice => 1,
1096 cb => &IO::AIO::poll_cb);
1097 CONTROLLING THE NUMBER OF THREADS
1099 IO::AIO::min_parallel $nthreads
1101 Set the minimum number of AIO threads to $nthreads. The current
1102 default is 8, which means eight asynchronous operations can execute
1103 concurrently at any one time (the number of outstanding requests,
1104 however, is unlimited).
1105 IO::AIO starts threads only on demand, when an AIO request is
1107 queued and no free thread exists. Please note that queueing up a
1108 hundred requests can create demand for a hundred threads, even if
1109 it turns out that everything is in the cache and could have been
1110 processed faster by a single thread.
1111 It is recommended to keep the number of threads relatively low, as
1113 some Linux kernel versions will scale negatively with the number of
1114 threads (higher parallelity => MUCH higher latency). With current
1115 Linux 2.6 versions, 4-32 threads should be fine.
1116 Under most circumstances you don't need to call this function, as
1118 the module selects a default that is suitable for low to moderate
1119 load.
1120 IO::AIO::max_parallel $nthreads
1122 Sets the maximum number of AIO threads to $nthreads. If more than
1123 the specified number of threads are currently running, this
1124 function kills them. This function blocks until the limit is
1125 reached.
1126 While $nthreads are zero, aio requests get queued but not executed
1128 until the number of threads has been increased again.
1129 This module automatically runs "max_parallel 0" at program end, to
1131 ensure that all threads are killed and that there are no
1132 outstanding requests.
1133 Under normal circumstances you don't need to call this function.
1135 IO::AIO::max_idle $nthreads
1137 Limit the number of threads (default: 4) that are allowed to idle
1138 (i.e., threads that did not get a request to process within 10
1139 seconds). That means if a thread becomes idle while $nthreads other
1140 threads are also idle, it will free its resources and exit.
1141 This is useful when you allow a large number of threads (e.g. 100
1143 or 1000) to allow for extremely high load situations, but want to
1144 free resources under normal circumstances (1000 threads can easily
1145 consume 30MB of RAM).
1146 The default is probably ok in most situations, especially if thread
1148 creation is fast. If thread creation is very slow on your system
1149 you might want to use larger values.
1150 IO::AIO::max_outstanding $maxreqs
1152 This is a very bad function to use in interactive programs because
1153 it blocks, and a bad way to reduce concurrency because it is
1154 inexact: Better use an "aio_group" together with a feed callback.
1155 Sets the maximum number of outstanding requests to $nreqs. If you
1157 do queue up more than this number of requests, the next call to the
1158 "poll_cb" (and "poll_some" and other functions calling "poll_cb")
1159 function will block until the limit is no longer exceeded.
1160 The default value is very large, so there is no practical limit on
1162 the number of outstanding requests.
1163 You can still queue as many requests as you want. Therefore,
1165 "max_outstanding" is mainly useful in simple scripts (with low
1166 values) or as a stop gap to shield against fatal memory overflow
1167 (with large values).
1168 STATISTICAL INFORMATION
1170 IO::AIO::nreqs
1172 Returns the number of requests currently in the ready, execute or
1173 pending states (i.e. for which their callback has not been invoked
1174 yet).
1175 Example: wait till there are no outstanding requests anymore:
1177 IO::AIO::poll_wait, IO::AIO::poll_cb
1179 while IO::AIO::nreqs;
1180 IO::AIO::nready
1182 Returns the number of requests currently in the ready state (not
1183 yet executed).
1184 IO::AIO::npending
1186 Returns the number of requests currently in the pending state
1187 (executed, but not yet processed by poll_cb).
1188 MISCELLANEOUS FUNCTIONS
1190 IO::AIO implements some functions that might be useful, but are not
1192 asynchronous.
1193 IO::AIO::sendfile $ofh, $ifh, $offset, $count
1195 Calls the "eio_sendfile_sync" function, which is like
1196 "aio_sendfile", but is blocking (this makes most sense if you know
1197 the input data is likely cached already and the output filehandle
1198 is set to non-blocking operations).
1199 Returns the number of bytes copied, or "-1" on error.
1201 IO::AIO::fadvise $fh, $offset, $len, $advice
1203 Simply calls the "posix_fadvise" function (see its manpage for
1204 details). The following advice constants are avaiable:
1205 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1206 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1207 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1208 On systems that do not implement "posix_fadvise", this function
1210 returns ENOSYS, otherwise the return value of "posix_fadvise".
1211 IO::AIO::madvise $scalar, $offset, $len, $advice
1213 Simply calls the "posix_madvise" function (see its manpage for
1214 details). The following advice constants are avaiable:
1215 "IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1216 "IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1217 "IO::AIO::MADV_DONTNEED".
1218 On systems that do not implement "posix_madvise", this function
1220 returns ENOSYS, otherwise the return value of "posix_madvise".
1221 IO::AIO::mprotect $scalar, $offset, $len, $protect
1223 Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1224 $scalar (see its manpage for details). The following protect
1225 constants are avaiable: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
1226 "IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1227 On systems that do not implement "mprotect", this function returns
1229 ENOSYS, otherwise the return value of "mprotect".
1230 IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1232 Memory-maps a file (or anonymous memory range) and attaches it to
1233 the given $scalar, which will act like a string scalar.
1234 The only operations allowed on the scalar are "substr"/"vec" that
1236 don't change the string length, and most read-only operations such
1237 as copying it or searching it with regexes and so on.
1238 Anything else is unsafe and will, at best, result in memory leaks.
1240 The memory map associated with the $scalar is automatically removed
1242 when the $scalar is destroyed, or when the "IO::AIO::mmap" or
1243 "IO::AIO::munmap" functions are called.
1244 This calls the "mmap"(2) function internally. See your system's
1246 manual page for details on the $length, $prot and $flags
1247 parameters.
1248 The $length must be larger than zero and smaller than the actual
1250 filesize.
1251 $prot is a combination of "IO::AIO::PROT_NONE",
1253 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1254 "IO::AIO::PROT_WRITE",
1255 $flags can be a combination of "IO::AIO::MAP_SHARED" or
1257 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1258 not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS"
1259 (which is set to "MAP_ANON" if your system only provides this
1260 constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
1261 "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or
1262 "IO::AIO::MAP_NONBLOCK"
1263 If $fh is "undef", then a file descriptor of "-1" is passed.
1265 $offset is the offset from the start of the file - it generally
1267 must be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
1268 Example:
1270 use Digest::MD5;
1272 use IO::AIO;
1273 open my $fh, "<verybigfile"
1275 or die "$!";
1276 IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
1278 or die "verybigfile: $!";
1279 my $fast_md5 = md5 $data;
1281 IO::AIO::munmap $scalar
1283 Removes a previous mmap and undefines the $scalar.
1284 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1286 Calls the "munlock" function, undoing the effects of a previous
1287 "aio_mlock" call (see its description for details).
1288 IO::AIO::munlockall
1290 Calls the "munlockall" function.
1291 On systems that do not implement "munlockall", this function
1293 returns ENOSYS, otherwise the return value of "munlockall".
1294
1296 It is recommended to use AnyEvent::AIO to integrate IO::AIO
1297 automatically into many event loops:
1298 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
1300 use AnyEvent::AIO;
1301 You can also integrate IO::AIO manually into many event loops, here are
1303 some examples of how to do this:
1304 # EV integration
1306 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
1307 # Event integration
1309 Event->io (fd => IO::AIO::poll_fileno,
1310 poll => 'r',
1311 cb => \&IO::AIO::poll_cb);
1312 # Glib/Gtk2 integration
1314 add_watch Glib::IO IO::AIO::poll_fileno,
1315 in => sub { IO::AIO::poll_cb; 1 };
1316 # Tk integration
1318 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
1319 readable => \&IO::AIO::poll_cb);
1320 # Danga::Socket integration
1322 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
1323 \&IO::AIO::poll_cb);
1324 FORK BEHAVIOUR
1326 This module should do "the right thing" when the process using it
1327 forks:
1328 Before the fork, IO::AIO enters a quiescent state where no requests can
1330 be added in other threads and no results will be processed. After the
1331 fork the parent simply leaves the quiescent state and continues
1332 request/result processing, while the child frees the request/result
1333 queue (so that the requests started before the fork will only be
1334 handled in the parent). Threads will be started on demand until the
1335 limit set in the parent process has been reached again.
1336 In short: the parent will, after a short pause, continue as if fork had
1338 not been called, while the child will act as if IO::AIO has not been
1339 used yet.
1340 MEMORY USAGE
1342 Per-request usage:
1343 Each aio request uses - depending on your architecture - around 100-200
1345 bytes of memory. In addition, stat requests need a stat buffer
1346 (possibly a few hundred bytes), readdir requires a result buffer and so
1347 on. Perl scalars and other data passed into aio requests will also be
1348 locked and will consume memory till the request has entered the done
1349 state.
1350 This is not awfully much, so queuing lots of requests is not usually a
1352 problem.
1353 Per-thread usage:
1355 In the execution phase, some aio requests require more memory for
1357 temporary buffers, and each thread requires a stack and other data
1358 structures (usually around 16k-128k, depending on the OS).
1359
1361 Known bugs will be fixed in the next release.
1362
1364 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
1365 more natural syntax.
1366
1368 Marc Lehmann <schmorp@schmorp.de>
1369 http://home.schmorp.de/
1370perl v5.12.3 2010-12-30 AIO(3)