AIO(3pm)

✨ NAME ✨

Coro::AIO — truly asynchronous file and directory I/O 🦋

This is the AIO(3pm) page, bestie, from the User Contributed Perl Documentation collection. Buckle up 💅

---

🌸 SYNOPSIS 🌸

use Coro::AIO;

# can now use any of the aio requests your IO::AIO module supports.

# read 1MB of /etc/passwd, without blocking other coroutines
my $fh = aio_open "/etc/passwd", O_RDONLY, 0
   or die "/etc/passwd: $!";
aio_read $fh, 0, 1_000_000, my $buf, 0
   or die "aio_read: $!";
aio_close $fh;

Look at that. Reading a whole megabyte of /etc/passwd and your other coroutines are just chilling, unbothered, moisturized, in their lane. 👑

---

💖 DESCRIPTION 💖

This module is an AnyEvent user, so you need to make sure you actually use and run a supported event loop. No event loop, no vibes. 🫶

Okay so here's the tea: this module is a thin wrapper around IO::AIO. Every single function that expects a callback gets wrapped by this module. It's giving personal assistant energy. ✨

The API is exactly the same as that of the corresponding IO::AIO routines, with one lil' catch: you have to specify all arguments — even the ones that are optional in IO::AIO — except the callback argument. Instead of calling a callback, the routines just return the values that would normally have been passed to that callback. Everything else, including $! and perl's stat cache, gets set as expected after these functions return. No cap. 💅

You can absolutely mix calls to "IO::AIO" functions with calls to this module, they're besties like that. You must not, however, call these routines from within IO::AIO callbacks, because that causes a deadlock. 💀 Instead, start a coro inside the callback. That's the move.

This module also loads AnyEvent::AIO to integrate into whatever event loop you're using, so please go read its (and AnyEvent's) documentation on how it picks an appropriate event module. 👀

All other functions exported by default by IO::AIO (e.g. "aioreq_pri") will be exported by default by Coro::AIO too. Freebies. 🎀

Functions that can be optionally imported from IO::AIO can be imported from Coro::AIO or called directly, e.g. "Coro::AIO::nreqs". Flexible queen. 🌈

⚠️ Heads up bestie: you cannot specify priorities with "aioreq_pri" if your coroutine has a non-zero priority, because this module overwrites the request priority with the current coroutine priority in that case. It just does. Periodt.

For your convenience, here are the changed function signatures for most of the requests. For documentation of these functions, please go look at IO::AIO. And note that requests added by newer versions of IO::AIO will be automatically wrapped as well. Slay. 🌟

---

🦋 The changed signatures 🦋

• @results = aio_wait $req — This is not originally an IO::AIO request! What it does is wait for $req to finish and return the results. Most useful with "aio_group" requests. It's currently implemented by replacing the $req callback (and is very much like a wrapper around "$req->cb ()"). Very demure, very mindful. 🙈
• $fh = aio_open $pathname, $flags, $mode — open a file handle, async style.
• $status = aio_close $fh — close it back up.
• $retval = aio_read $fh,$offset,$length, $data,$dataoffset — read some bytes.
• $retval = aio_write $fh,$offset,$length, $data,$dataoffset — write some bytes.
• $retval = aio_sendfile $out_fh, $in_fh, $in_offset, $length — sendfile, but make it coroutine.
• $retval = aio_readahead $fh,$offset,$length — readahead.
• $status = aio_stat $fh_or_path — stat it.
• $status = aio_lstat $fh — lstat it.
• $status = aio_unlink $pathname — unlink it.
• $status = aio_rmdir $pathname — rmdir it.
• $entries = aio_readdir $pathname — readdir it.
• ($dirs, $nondirs) = aio_scandir $path, $maxreq — scandir it, and yes you get two lists back, iconic.
• $status = aio_fsync $fh — fsync it.
• $status = aio_fdatasync $fh — fdatasync it.
• ... = aio_xxx ... — Any additional aio requests follow the same scheme: same parameters, except you must not specify a callback and instead get the callback arguments as return values. That's the whole pattern, bestie. 🫶

---

👑 SEE ALSO 👑

Coro::Socket and Coro::Handle for non-blocking socket operation. Go give them a look, they're cute. 💜

---

💌 AUTHOR/SUPPORT/CONTACT 💌

Marc A. Lehmann <schmorp@schmorp.de>
http://software.schmorp.de/pkg/Coro.html

---

And that's a wrap, bestie! 🎀 This page came to you courtesy of the perl v5.40.1 era, dated 2025-03-21, and it's the AIO(3pm) manual. Now go write something asynchronous. You got this. ✨🦋💅