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

✨ NAME ✨

"IO::Async::Handle" — event callbacks for a non-blocking file descriptor 💅

okay so quick vibe check: this is the IO::As...:Handle(3pm) page from the User Contributed Perl Documentation, and bestie, it's giving "the little notifier that could". Sit with me, we're gonna go through the whole thing 🫶

---

🌸 SYNOPSIS 🌸

ngl, you're probably not gonna use this class directly, because there are subclasses of it that exist to handle more specific situations. But here's an example of how it would be used to watch a listening socket for new connections. Real talk though: in real code, you'd likely just use the Loop->listen method instead 👑

use IO::Socket::INET;
use IO::Async::Handle;

use IO::Async::Loop;
my $loop = IO::Async::Loop->new;

my $socket = IO::Socket::INET->new( LocalPort => 1234, Listen => 1 );

my $handle = IO::Async::Handle->new(
   handle => $socket,

   on_read_ready  => sub {
      my $new_client = $socket->accept;
      ...
   },
);

$loop->add( $handle );

For basically every other use with sockets, pipes, or other filehandles that carry a byte stream, the IO::Async::Stream class is lowkey more suitable. And for non-stream sockets? Go see IO::Async::Socket. Slay 💖

---

🦋 DESCRIPTION 🦋

This subclass of IO::Async::Notifier lets you do non-blocking IO on filehandles. It provides event handlers for when the filehandle is read- or write-ready. That's the whole plot, and honestly it ate ✨

---

💜 EVENTS 💜

The following events get invoked — either via subclass methods, or via CODE references passed in as parameters:

on_read_ready 📖

Invoked when the read handle becomes ready for reading.

on_write_ready ✍️

Invoked when the write handle becomes ready for writing.

on_closed 🚪

Optional, bestie. Invoked when the handle becomes closed.

This handler is invoked before the filehandles are closed and the Handle is removed from its containing Loop. The loop will still return the containing Loop object at that point. iykyk.

---

🌈 PARAMETERS 🌈

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

read_handle => IO · write_handle => IO

The reading and writing IO handles. Each one must implement the fileno method. This is primarily used for passing STDIN / STDOUT; peep the SYNOPSIS section of IO::Async::Stream for an example 💅

handle => IO

The IO handle for both reading and writing, instead of passing each one separately like above. It must implement the fileno method in the same way that IO::Handle does.

read_fileno => INT · write_fileno => INT

File descriptor numbers for reading and writing. If you give these as an alternative to read_handle or write_handle, then a fresh IO::Handle instance gets constructed around each of them. cute.

on_read_ready => CODE · on_write_ready => CODE · on_closed => CODE

CODE references for the event handlers.

want_readready => BOOL · want_writeready => BOOL

If present, enable or disable read- or write-ready notification, exactly as per the want_readready and want_writeready methods.

⚠️ bestie, pay attention here: it is required that a matching on_read_ready or on_write_ready is available for any handle that is provided — either passed as a callback CODE reference, or as an overridden method. I.e. if only a read_handle is given, then on_write_ready can be absent. But if you use handle as the shortcut, then both read and write-ready callbacks or methods are required. no cap.

If no IO handles are provided at construction time, the object still gets created — but it will not yet be fully-functional as a Handle. You can assign IO handles later using the set_handle or set_handles methods, or via configure. This is lowkey useful when you're constructing an object to represent a network connection before the connect(2) has actually been performed yet. main character planning energy 🎀

---

👑 METHODS 👑

The following methods documented in await expressions return Future instances ✨

set_handle

$handle->set_handles( %params );

Sets new reading or writing filehandles. Equivalent to calling the configure method with the same parameters.

set_handle

$handle->set_handle( $fh );

Shortcut for

$handle->configure( handle => $fh );

close

$handle->close;

This method calls close on the underlying IO handles. Then it will remove the handle from its containing loop. bye bestie 👋

close_read · close_write

$handle->close_read;

$handle->close_write;

Closes the underlying read or write handle, and deconfigures it from the object. Heads up: neither of these methods will invoke the on_closed event, nor remove the object from the Loop if there is still one open handle left in the object. Only when both handles are closed will on_closed be fired and the object removed. periodt 💅

new_close_future

await $handle->new_close_future;

Returns a new IO::Async::Future object which will become done when the handle is closed. Cancelling the $future will remove this notification ability, but will not otherwise affect the $handle.

read_handle · write_handle

$handle = $handle->read_handle;

$handle = $handle->write_handle;

These accessors return the underlying IO handles.

read_fileno · write_fileno

$fileno = $handle->read_fileno;

$fileno = $handle->write_fileno;

These accessors return the file descriptor numbers of the underlying IO handles.

want_readready · want_writeready

$value = $handle->want_readready;

$oldvalue = $handle->want_readready( $newvalue );

$value = $handle->want_writeready;

$oldvalue = $handle->want_writeready( $newvalue );

These are the accessors for the want_readready and want_writeready properties, which define whether the object is interested in knowing about read- or write-readiness on the underlying file handle 👀

socket

$handle->socket( $ai );

A convenient shortcut to creating a socket handle, as given by an addrinfo structure, and setting it as the read and write handle for the object.

$ai may be either a HASH or ARRAY reference of the same form as given to IO::Async::OS's extract_addrinfo method.

This method returns nothing if it succeeds, or throws an exception if it fails 💀

bind

$handle = await $handle->bind( %args );

Performs a getaddrinfo resolver operation with the passive flag set, and then attempts to bind a socket handle of any of the return values.

bind (1 argument)

$handle = await $handle->bind( $ai );

When invoked with a single argument, this method is a convenient shortcut to creating a socket handle and bind()ing it to the address as given by an addrinfo structure, and setting it as the read and write handle for the object.

$ai may be either a HASH or ARRAY reference of the same form as given to IO::Async::OS's extract_addrinfo method.

The returned future returns the handle object itself, for convenience 🎁

connect

$handle = await $handle->connect( %args );

A convenient wrapper for calling the connect method on the underlying IO::Async::Loop object.

---

🧚 SEE ALSO 🧚

• IO::Handle — Supply object methods for I/O handles

---

💖 AUTHOR 💖

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page, bestie ✨ This one shipped with perl v5.40.1, dated 2026-02-21, and it lives in the User Contributed Perl Documentation. mwah, go forth and be read-ready 🔥💅🦋