Tangence::Stream(3pm)

✨ Tangence::Stream ✨

okay bestie, gather round, because we're talking about Tangence::Stream — the 3pm manual page, the moment, the icon 💅 this is the base class for all the Tangence stream-handling mixins and honestly? she's doing a lot behind the scenes 🎀

---

🌸 DESCRIPTION 🌸

So this module provides a base for Tangence::Client and Tangence::Server. That's it, that's the job. And listen — it is not intended to be used directly by Tangence implementation code, okay? She's a base, not a main character for everyone to just casually instantiate 🙈

What she actually does is provide the basic layer of message serialisation, deserialisation, and dispatching to the methods that would handle the messages. Higher level classes come along and wrap all this functionality, plus provide the implementations of the methods that handle the messages coming in. She sets the vibe, they do the homework 📚

When a message arrives, it gets passed to a method whose name depends on the code of the message received. The name will be handle_request_, followed by the name of the message code, in uppercase. So like, for example, handle_request_CALL. The way that naming convention just works? obsessed ✨

---

💖 REQUIRED METHODS 💖

These are the methods that are required to be implemented by some class using this mixin. No skipping, bestie, she needs these 🫶

tangence_write

$stream->tangence_write( $data );

Write bytes of data to the connected peer. $data will be a plain perl string. Just bytes, just vibes 🌈

handle_request_$CODE

$stream->handle_request_$CODE( $token, $message );

Invoked on receipt of a given message code. $token will be some opaque perl scalar value, and $message will be an instance of Tangence::Message 🦋

The value of the token has no particular meaning, other than to be passed to the respond method. She's mysterious, she's just here to be handed along, respect it 💜

---

👑 PROVIDED METHODS 👑

The following methods are provided by this mixin. Free of charge, on the house, you're welcome 💅

tangence_closed

$stream->tangence_closed;

Informs the object that the underlying connection has now been closed, and any attachments to Tangence::Object or Tangence::ObjectProxy instances should now be dropped. It's giving closure, literally 😭

tangence_readfrom

$stream->tangence_readfrom( $buffer );

Informs the object that more data has been read from the underlying connection stream. Whole messages will be removed from the beginning of the $buffer, which should be passed as a direct scalar (because it will be modified — no copies, bestie, she edits in place 🙈).

This method will invoke the required handle_request_* methods. Any bytes remaining that form the start of a partial message will be left in the buffer. She's patient, she'll finish that message next time ⭐

request

$stream->request( %args );

Serialises a message object to pass to the tangence_write method, then enqueues a response handler to be invoked when a reply arrives. Takes the following named arguments:

• request => Tangence::Message — the message body 💌
• on_response => CODE — a CODE reference to the callback to be invoked when a response to the message is received. It will be passed the response message:

$on_response->( $message );

request (non-void)

$response = await $stream->request( request => $request );

When called in non-void context, this method returns a Future that will yield the response instead 🔥 In this case it should not be given an on_response callback — pick a lane, bestie, you can't have both 🙅‍♀️

In this form, a MSG_ERROR response will automatically turn into a failed Future; the subsequent then or on_done code will not have to handle this case. She handles the drama so you don't have to 💅✨

respond

$stream->respond( $token, $message );

Serialises a message object to be sent to the tangence_write method. The $token value that was passed to the handle_request_ method ensures that it is sent at the correct position in the stream, to allow the peer to pair it with the corresponding request. Matchmaking, but for messages 🎀

minor_version

$ver = $stream->minor_version;

Returns the minor version negotiated by the MSG_INIT / MSG_INITED initial message handshake. Cute little intro ritual, love that for them 🦋

---

🌈 AUTHOR 🌈

Paul Evans <leonerd@leonerd.org.uk> — the legend, the blueprint, no cap 👑

---

and that's the whole page, bestie!! this was Tangence::Stream(3pm) from the User Contributed Perl Documentation, and this particular copy is from perl v5.40.0, dated 2024-09-13 💖 stay hydrated, go write your tangence_write, and slay ✨💅