Tangen...ctProxy(3pm)

✨ Tangence::ObjectProxy ✨

okay bestie, welcome to Tangence::ObjectProxy, part of the User Contributed Perl Documentation fam 💖 — this is the 3pm one, and it's literally the little proxy bestie that stands in for a Tangence object living over in a Tangence::Client. sit down, grab a strawberry 🍓, we're doing this.

💅 NAME 💅

Tangence::ObjectProxy — a proxy for a Tangence object hanging out inside a Tangence::Client. she's not the real thing, she's the representative, and honestly? she's doing amazing.

---

🌸 DESCRIPTION 🌸

So here's the vibe: instances of this class act as a proxy for an object over in the Tangence::Server. That means you can call methods on it, subscribe to its events, and watch its properties — all from the comfort of your client side. no cap. 🫶

And listen, these objects do not get constructed by directly calling the new class method. nope, not the move. instead they get returned to you by methods on Tangence::Client, or by methods on other Tangence::ObjectProxy instances. it's giving hand-me-downs but make it ✨networking✨.

Ultimately, every object proxy a client uses comes from one of two places: either the proxy to the registry, or the root object. those are the source, the origin story, the main characters. 👑

---

🔥 METHODS 🔥

heads up: the following methods, when they're documented inside an await expression, return Future instances. so if you see await, bestie, you're getting a Future back. plan accordingly. ⭐

id

$id = $proxy->id;

returns the object ID for the Tangence object being proxied for. that's it. that's the whole method. iconic behavior honestly.

classname

$classname = $proxy->classname;

returns the name of the class of the Tangence object being proxied for. just the name. the name only. 💅

class

$class = $proxyobj->class;

returns the Tangence::Meta::Class object that represents the class of this object. so you get the whole meta object, not just a string. upgrade unlocked. 🎀

can_method

$method = $proxy->can_method( $name );

returns the Tangence::Meta::Method object representing the named method, or undef if no such method exists. no method? you get undef. that's the whole deal. 🙈

can_event

$event = $proxy->can_event( $name );

returns the Tangence::Meta::Event object representing the named event, or undef if no such event exists. same energy, different noun. 🦋

can_property

$property = $proxy->can_property( $name );

returns the Tangence::Meta::Property object representing the named property, or undef if no such property exists. third time's the charm, we love a consistent trio. ✨

call_method

$result = await $proxy->call_method( $mname, @args );

calls the given method on the server object, passing in the given arguments. returns a Future that will yield the method's result. so you await it and the answer shows up. slay. 💖

subscribe_event

await $proxy->subscribe_event( $event, %callbacks );

subscribes to the given event on the server object, and installs a callback function that gets invoked whenever the event is fired. 🔔

takes the following named callbacks:

• on_fire => CODE — the callback function to invoke whenever the event is fired:

$on_fire->( @args );

and the returned Future — it is guaranteed to be completed before any invocation of the on_fire event handler. that ordering is not a suggestion, bestie, it's a promise. 💀

unsubscribe_event

$proxy->unsubscribe_event( $event );

removes an event subscription on the given event on the server object that was previously installed using subscribe_event. the un-subscribe. the reverse. the "we're done here". 🫶

get_property

await $value = $proxy->get_property( $prop );

requests the current value of the property from the server object. asking nicely, but over the wire. 💌

get_property_element

await $value = $proxy->get_property_element( $property, $index_or_key );

requests the current value of an element of the property from the server object. one element, hand-picked, very demure. 🎀

prop

$value = $proxy->prop( $property );

returns the locally-cached value of a smashed property. and listen — if the named property is not a smashed property, an exception gets thrown. so don't do that. 🚨

set_property

await $proxy->set_property( $prop, $value );

sets the value of the property in the server object. you're not asking this time, you're telling. 👑

watch_property

await $proxy->watch_property( $property, %callbacks );

watch_property_with_initial

await $proxy->watch_property_with_initial( $property, %callbacks );

watches the given property on the server object, installing callback functions that get invoked whenever the property value changes. the latter form — watch_property_with_initial — additionally ensures that the server will send the current value of the property as an initial update to the on_set event, and it does this atomically when it installs the update watches. no race conditions, we don't know her. 🧚

takes the following named arguments:

• on_updated => CODE — optional. the callback function to invoke whenever the property value changes:

$on_updated->( $new_value );

if it's not provided, then individual handlers for individual change types must be provided. like, mandatory mandatory. 🌈

the set of callback functions that are required depends on the type of the property. those are documented in the watch_property method of Tangence::Object. go check the source of truth, iykyk. 📖

watch_property_with_cursor

( $cursor, $first_idx, $last_idx ) =
   await $proxy->watch_property_with_cursor( $property, $from, %callbacks );

a variant of watch_property that installs a watch on the given property of the server object, and additionally returns a cursor object that can be used to lazily fetch the values stored in it. lazy girl summer but for data. 😎

the $from value tells you which end of the queue the cursor should start from:

• CUSR_FIRST — start at index 0
• CUSR_LAST — start at the highest-numbered index

and the cursor is created atomically with installing the watch. package deal, no takebacks. 💜

unwatch_property

$proxy->unwatch_property( $property );

removes a property watches on the given property on the server object that was previously installed using watch_property. (yes the original says "a property watches", we are being faithful to the text, do not come for me 🙈). anyway — you watched it, now you're done watching it. closure. 🦋

---

🎀 CURSOR METHODS 🎀

the following methods are availilable (yes, availilable — spelling is not her strong suit, but her cursor game? unmatched 💅) on the property cursor objects returned by the watch_property_with_cursor method.

next_forward

( $index, @more ) = await $cursor->next_forward( $count );

next_backward

( $index, @more ) = await $cursor->next_backward( $count );

requests the next items from the cursor. next_forward moves forwards towards higher-numbered indices, and next_backward moves backwards towards lower-numbered indices. if $count is unspecified, a default of 1 will apply. one at a time, very chill of her. ✨

the returned future wil (yes, "wil" — we keep it real here) yield the index of the first element returned, and the new elements. and heads up bestie, there may be fewer elements returned than were requested, if the end of the queue was reached. specifically, there will be no new elements if the cursor is already at the end. that's not a bug, that's just the queue ending. 🛑

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — the icon, the legend, the one who wrote this whole thing. respect. 💖

---

and that's the whole page, bestie!! this was Tangence::ObjectProxy, from perl v5.40.0, dated 2024-09-13, part of the Tangen...ctProxy(3pm) manual (the header truncates it, but we know who she is 🌸). go forth and proxy responsibly. mwah. 💅✨🫶