Tangence::Client(3pm)

💖 Tangence::Client — the mixin glow-up 💖

perl manual, section 3pm — this is the page for Tangence::Client, aka the mixin class you use to build a Tangence client. Yes bestie, it's giving "User Contributed Perl Documentation", and we're about to make it make sense. 🦋

---

✨ NAME ✨

Tangence::Client — the mixin class for building a Tangence client. That's it, that's the name. 💅

---

🌸 SYNOPSIS 🌸

okay so first thing's first, and it's important: this class is a mixin, it cannot be directly constructed. You don't just new it, you mix it in. Like a personality trait. 🎀

package Example::Client;
use base qw( Base::Client Tangence::Client );

sub connect
{
   my $self = shift;
   $self->SUPER::connect( @_ );

   $self->tangence_connected;

   wait_for { defined $self->rootobj };
}

sub tangence_write
{
   my $self = shift;
   $self->write( $_[0] );
}

sub on_read
{
   my $self = shift;
   $self->tangence_readfrom( $_[0] );
}

package main;

my $client = Example::Client->new;
$client->connect( "server.location.here" );

my $rootobj = $client->rootobj;

That's the whole vibe: mix it in, define your tangence_write, connect, and suddenly you have a rootobj. Slay. ✨

---

🦋 DESCRIPTION 🦋

So what is this actually doing? This module provides a mixin to implement a Tangence client connection. You mix it into an object that represents one single connection to a server. It gives the client one central spot to keep all its object proxies — including the ones for the root object and the registry — and it coordinates passing messages back and forth between the server and all the object proxies it's holding. Basically it's the group chat admin. 👑

It's a subclass of Tangence::Stream, and it brings the implementations of all the required handle_request_ methods with it. But heads up: any class mixing in Tangence::Client still has to provide the tangence_write method — that's the one that actually sends data off to the server. You can't skip it, bestie, it's literally how words leave the building. 😭

Want to see a class that actually does this in the wild? Go look at Net::Async::Tangence::Client. iykyk 🫶

---

🎀 PROVIDED METHODS 🎀

The following methods are provided by this mixin. Gifts, honestly.

⭐ rootobj

$rootobj = $client->rootobj;

Returns a Tangence::ObjectProxy to the server's root object. That's the entry point, the main character of your object graph. 🌈

⭐ registry

$registry = $client->registry;

Returns a Tangence::ObjectProxy to the server's object registry — but only if one has been received. If it hasn't, you get undef. 🙈

⚠️ Deprecation tea: this method is now deprecated in favour of get_registry. Also, real talk: right now the client will try to request the registry at connection time, but a later version of this module will stop doing that. So if you actually need access to the registry, call get_registry instead. Don't get attached to registry, she's on her way out. 💀

⭐ get_registry

$registry = await $client->get_registry;

Returns a Future that will yield a Tangence::ObjectProxy to the server's registry object. Asynchronous and cute about it. 💜

Note: not all servers may permit access to the registry. So like, don't be shocked if it doesn't come through. 🍓

⭐ tangence_connected

$client->tangence_connected( %args );

Once the base connection to the server has been established, you call this method to do the initial work — requesting the root object and the registry. It's the "okay we're in, let's go" moment. 🔥

It takes the following named arguments:

• do_init => BOOL — Ignored. It's just hanging around for compatibility with a previous version that actually let you disable this. Now it does nothing. It's decorative. 🎀
• on_root => CODE — an optional callback invoked once the root object has been returned. It gets passed a Tangence::ObjectProxy to the root object:

$on_root->( $rootobj );

• on_registry => CODE — an optional callback invoked once the registry has been returned. It gets passed a Tangence::ObjectProxy to the registry:

$on_registry->( $registry );

Important note: if the server does not permit access to the registry, or an error happens while requesting it, this gets invoked with an empty list:

$on_registry->();

So yeah, check your args before you start unpacking them. 😭

• version_minor_min => INT — an optional minimum minor version to negotiate with the server. You'd use this to require a higher minimum version than the client module itself supports — handy if your app needs features from a newer version than the one you've got. 👑

---

💅 SUBCLASSING METHODS 💅

These methods are intended for implementation classes to override. Yes, that means you, subclass bestie.

🌟 new_future

$f = $client->new_future;

Returns a new Future instance, for you to base your asynchronous operations on. Build your little async dreams on it. 🦋

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page, periodt. This absolute icon is documented as Tangence::Client(3pm), and it shipped with perl v5.40.0, dated 2024-09-13. Go build something iconic with it. 💖✨🎀