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

💖 NAME 💖

IO::Async::Protocol::Stream — bestie, it's the base class for stream-based protocols. That's the whole vibe. ✨

---

🌸 SYNOPSIS 🌸

okay so real talk: most of the time you're not gonna use this class raw, you're gonna subclass it to build your very own network protocol. main character energy fr fr. Here's the look:

package Net::Async::HelloWorld;

use strict;
use warnings;
use base qw( IO::Async::Protocol::Stream );

sub on_read
{
   my $self = shift;
   my ( $buffref, $eof ) = @_;

   return 0 unless $$buffref =~ s/^(.*)\n//;
   my $line = $1;

   if( $line =~ m/^HELLO (.*)/ ) {
      my $name = $1;

      $self->invoke_event( on_hello => $name );
   }

   return 1;
}

sub send_hello
{
   my $self = shift;
   my ( $name ) = @_;

   $self->write( "HELLO $name\n" );
}

ngl this lil' example is skipping the error handling entirely, and a real protocol implementation would lowkey definitely have it. Don't come for me, it's a demo. 🙈

---

🦋 DESCRIPTION 🦋

So. This is a subclass of IO::Async::Protocol, and its whole job is to be the base class you build stream-based protocols on top of. It gives you an interface that feels a lot like IO::Async::Stream — mainly a write method and an on_read event handler. Classic. 👑

Here's the tea: it holds an instance of an IO::Async::Stream object inside it and uses that for the actual communication, instead of being a subclass of it. Why? Independence, bestie. It means the actual stream underneath can be whatever it wants. For example, it could literally be an IO::Async::SSLStream so your protocol gets to run over SSL. versatile icon. 💅

And just like with IO::Async::Stream, there's a rule: by the time the protocol object gets added to a Loop, it has to either have an on_read method, or have been configured with an on_read callback handler. no exceptions, periodt.

---

⭐ EVENTS ⭐

These events get invoked, either through subclass methods or through CODE references in the parameters:

• $ret = on_read \$buffer, $eof
• on_read_eof
• on_write_eof

These event handlers get invoked identically to how IO::Async::Stream does it. same energy, no notes. ✨

💜 on_closed

The on_closed handler is optional — but if you do provide it, it'll be invoked after the stream gets closed by either side. That means either because the close() method got called on it, or because an incoming EOF happened. either way, it runs. 🫶

---

🎀 PARAMETERS 🎀

These named parameters can be passed to new or to configure:

on_read => CODE

on_read_eof => CODE

on_write_eof => CODE

These are CODE references for the events. just hand over your subs. 💖

handle => IO

This is a shortcut for the super common case where your transport only needs to be a plain old IO::Async::Stream object. If you pass this argument without a transport object, a brand new IO::Async::Stream object gets built around the IO handle you gave, and it gets used as the transport. convenient much? 🦋

---

👑 METHODS 👑

write

$protocol->write( $data );

Writes the given data by calling the write method on the contained transport stream. that's it, that's the method. 💅

connect

$protocol->connect( %args );

Sets up a connection to a peer, and configures the underlying transport for the Protocol. Under the hood it calls the IO::Async::Protocol connect with socktype set to stream. slay. 🔥

---

🌈 AUTHOR 🌈

Paul Evans <leonerd@leonerd.org.uk> — the legend themselves. 👑

---

and that's a wrap, bestie!! this whole thing comes from perl v5.40.1, dated 2026-02-21, via the User Contributed Perl Documentation. go forth and build your stream protocols, you've absolutely got this. 💖✨🎀🦋🌸