Tangence::ObjectProxy - proxy for a
Tangence object in a
Instances in this class act as a proxy for an object in the Tangence::Server, allowing methods to be called, events to be subscribed to, and properties to be watched.
These objects are not directly constructed by calling the
new class method; instead they are returned by methods on Tangence::Client,
or by methods on other
Ultimately every object proxy that a client uses will come from either the proxy to the registry,
or the root object.
The following methods documented with a trailing call to
->get return Future instances.
$id = $proxy->id
Returns the object ID for the
Tangence object being proxied for.
$classname = $proxy->classname
Returns the name of the class of the
Tangence object being proxied for.
$class = $proxyobj->class
Returns the Tangence::Meta::Class object representing the class of this object.
$method = $proxy->can_method( $name )
Returns the Tangence::Meta::Method object representing the named method, or
undef if no such method exists.
$event = $proxy->can_event( $name )
Returns the Tangence::Meta::Event object representing the named event, or
undef if no such event exists.
$property = $proxy->can_property( $name )
Returns the Tangence::Meta::Property object representing the named property, or
undef if no such property exists.
$result = $proxy->call_method( $mname, @args )->get
Calls the given method on the server object, passing in the given arguments. Returns a Future that will yield the method's result.
$proxy->subscribe_event( $event, %callbacks )->get
Subscribes to the given event on the server object, installing a callback function which will be invoked whenever the event is fired.
Takes the following named callbacks:
Callback function to invoke whenever the event is fired
$on_fire->( @args )
Future it is guaranteed to be completed before any invocation of the
on_fire event handler.
$proxy->unsubscribe_event( $event )
Removes an event subscription on the given event on the server object that was previously installed using
$value = $proxy->get_property( $prop )->get
Requests the current value of the property from the server object.
$value = $proxy->get_property_element( $property, $index_or_key )->get
Requests the current value of an element of the property from the server object.
$value = $proxy->prop( $property )
Returns the locally-cached value of a smashed property. If the named property is not a smashed property, an exception is thrown.
$proxy->set_property( $prop, $value )->get
Sets the value of the property in the server object.
$proxy->watch_property( $property, %callbacks )->get
$proxy->watch_property_with_initial( $property, %callbacks )->get
Watches the given property on the server object, installing callback functions which will be invoked whenever the property value changes. The latter form additionally ensures that the server will send the current value of the property as an initial update to the
on_set event, atomically when it installs the update watches.
Takes the following named arguments:
Optional. Callback function to invoke whenever the property value changes.
$on_updated->( $new_value )
If not provided, then individual handlers for individual change types must be provided.
The set of callback functions that are required depends on the type of the property. These are documented in the
watch_property method of Tangence::Object.
( $iter, $first_idx, $last_idx ) = $proxy->watch_property_with_iter( $property, $iter_from, %callbacks )->get
A variant of
watch_property that installs a watch on the given property of the server object, and additionally returns an iterator object that can be used to lazily fetch the values stored in it.
$iter_from value indicates which end of the queue the iterator should start from;
ITER_FIRST to start at index 0, or
ITER_LAST to start at the highest-numbered index. The iterator is created atomically with installing the watch.
$proxy->unwatch_property( $property )
Removes a property watches on the given property on the server object that was previously installed using
The following methods are availilable on the property iterator objects given to the
on_iter callback of a
( $index, @more ) = $iter->next_forward( $count )->get
( $index, @more ) = $iter->next_backward( $count )->get
Requests the next items from the iterator.
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.
The returned future wil yield the index of the first element returned, and the new elements. Note that 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 iterator is already at the end.
Paul Evans <email@example.com>