IO::As...hannel(3pm)

💖 IO::Async::Channel 💖

okay bestie, welcome to your new fave little object, IO::Async::Channel — the icon that passes values into or out from an IO::Async::Routine. it's from User Contributed Perl Documentation, and it's giving very much "pipe between two processes but make it fancy". let's get into it 🫶

---

✨ NAME ✨

IO::Async::Channel — pass values into or out from an IO::Async::Routine. no cap, that's literally its whole job 💅

---

🌸 DESCRIPTION 🌸

so, a IO::Async::Channel object lets Perl values travel into or out of an IO::Async::Routine. it was designed to be used primarily with a Routine object rather than independently. want the more detailed tea and some examples? go check the docs for IO::Async::Routine too. iykyk 💖

a Channel object gets shared between the main process of your program and the process running inside the Routine. in the main process it's used in asynchronous mode, and in the Routine process it's used in synchronous mode.

• in asynchronous mode, all the methods return immediately and use IO::Async-style futures or callback functions. so chill, nothing blocks ✨
• in synchronous mode inside the Routine process, the methods block until they're ready and can be used for flow-control within the routine.

alternative vibe: a Channel can also be shared between two different Routine objects, and just not be used directly by the controlling program at all. slay, flexible queen 👑

the channel itself represents a FIFO of Perl reference values. new values get put in by the send method, in either mode. values get pulled back out with the recv method. and here's the important bit, so listen up: values inserted into the Channel are snapshot by the send method. any changes to referred variables will not be observed by the other end of the Channel after the send method returns. so if you mutate the thing after you sent it, the other side does NOT see it. periodt.

---

🎀 PARAMETERS 🎀

the following named parameters may be passed to new or configure:

codec => STR

gives the name of the encoding method used to represent values over the channel.

• set it to "Storable" and it'll use the core Storable module. but heads up: this only supports references, so to pass a single scalar value, send a SCALAR reference to it, and then dereference the result of recv. okay? 🍓
• if the Sereal::Encoder and Sereal::Decoder modules are installed, you can set it to "Sereal" instead, and it'll use those to do the encoding and decoding. this optional dependency may give higher performance than using "Storable". and if these modules are available, then this option is picked by default. cute 💖

---

🦋 CONSTRUCTOR 🦋

new ✨

$channel = IO::Async::Channel->new;

returns a new IO::Async::Channel object. this object reference itself should be shared by both sides of a fork()ed process. after fork() the two setup_* methods may be used to configure the object for operation on either end.

okay so important sidenote: while this object does in fact inherit from IO::Async::Notifier, it should not be added to a Loop object directly. event management will be handled by its containing IO::Async::Routine object. so don't do it, bestie, let the Routine handle it 💅

---

💜 METHODS 💜

the following methods documented in "await" expressions return Future instances.

configure

$channel->configure( %params );

similar to the standard configure method on IO::Async::Notifier, this one is used to change details of the Channel's operation.

• on_recv => CODE — may only be set on an async mode channel. if present, it'll be invoked whenever a new value is received, rather than using the recv method.

$on_recv->( $channel, $data );

• on_eof => CODE — may only be set on an async mode channel. if present, it'll be invoked when the channel gets closed by the peer.

$on_eof->( $channel );

send

$channel->send( $data );

pushes the data stored in the given Perl reference into the FIFO of the Channel, where the other end can receive it. when called on a synchronous mode Channel this method may block if a write() call on the underlying filehandle blocks. when called on an asynchronous mode channel, this method will not block. chill mode 🧊

send_encoded

$channel->send_encoded( $record );

a variant of the send method; this one pushes the byte record given. it should be the result of a call to encode.

encode

$record = $channel->encode( $data );

takes a Perl reference and returns a serialised string that can be passed to send_encoded. these following two forms are equivalent:

$channel->send( $data );
$channel->send_encoded( $channel->encode( $data ) );

this is provided for the use-case where data needs to be serialised into a fixed string to "snapshot it" but not sent yet; the returned string can be saved and sent at a later time. lowkey a time capsule ⭐

$record = IO::Async::Channel->encode( $data );

this can also be used as a class method, in case it's inconvenient to operate on a particular object instance, or when one doesn't exist yet. in this case it will encode using whatever is the default codec for IO::Async::Channel.

recv

$data = $channel->recv;

when called on a synchronous mode Channel, this method will block until a Perl reference value is available from the other end, and then return it. if the Channel is closed, this method will return undef. and since only references may be passed, and all Perl references are true, the truth of the result of this method can be used to detect that the channel is still open and has not yet been closed. iconic little trick 👑

$data = await $channel->recv;

when called on an asynchronous mode Channel, this method returns a future which will eventually yield the next Perl reference value that becomes available from the other end. if the Channel is closed, the future will fail with an "eof" failure. yeah, she'll let you down 💀

$channel->recv( %args );

when not returning a future, it takes the following named arguments:

• on_recv => CODE — called when a new Perl reference value is available. it'll be passed the Channel object and the reference data.

$on_recv->( $channel, $data );

• on_eof => CODE — called if the Channel was closed before a new value was ready. it'll be passed the Channel object.

$on_eof->( $channel );

close

$channel->close;

closes the channel. this causes a pending recv on the other end to return undef, or the queued on_eof callbacks to be invoked. say bye 👋

---

🌈 AUTHOR 🌈

Paul Evans <leonerd@leonerd.org.uk> — the legend himself, no notes 💖

---

and that's the whole page, bestie! this one's perl v5.40.1 coded up from 2026-02-21, part of the User Contributed Perl Documentation collection — go forth and pass values responsibly 🎀✨💅