NAME

Tangence::ObjectProxy - proxy for a Tangence object in a Tangence::Client

DESCRIPTION

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 Tangence::ObjectProxy instances. Ultimately every object proxy that a client uses will come from either the proxy to the registry, or the root object.

METHODS

$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.

$proxy->call_method( %args )

Calls the given method on the server object and invokes a callback function when a result is received.

Takes the following named arguments:

method => STRING

The name of the method

args => ARRAY

Optional. If provided, gives positional arguments for the method.

on_result => CODE

Callback function to invoke when a result is returned

 $on_result->( $result )

on_error => CODE

Optional. Callback function to invoke when an error is returned. The client's default will apply if not provided.

 $on_error->( $error )

$proxy->subscribe_event( %args )

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 arguments:

event => STRING

Name of the event

on_fire => CODE

Callback function to invoke whenever the event is fired

 $on_fire->( @args )

on_subscribed => CODE

Optional. Callback function to invoke once the event subscription is successfully installed by the server.

 $on_subscribed->()

If this is provided, it is guaranteed to be invoked before any invocation of the on_fire event handler.

on_error => CODE

Optional. Callback function to invoke when an error is returned. The client's default will apply if not provided.

 $on_error->( $error )

$proxy->unsubscribe_event( %args )

Removes an event subscription on the given event on the server object that was previously installed using subscribe_event.

Takes the following named arguments:

event => STRING

Name of the event

$proxy->get_property( %args )

Requests the current value of the property from the server object, and invokes a callback function when the value is received.

Takes the following named arguments

property => STRING

The name of the property

on_value => CODE

Callback function to invoke when the value is returned

 $on_value->( $value )

on_error => CODE

Optional. Callback function to invoke when an error is returned. The client's default will apply if not provided.

 $on_error->( $error )

$proxy->get_property_element( %args )

Requests the current value of an element of the property from the server object, and invokes a callback function when the value is received.

Takes the following named arguments

property => STRING

The name of the property

index => INT

For queue or array dimension properties, the index of the element

key => STRING

For hash dimension properties, the key of the element

on_value => CODE

Callback function to invoke when the value is returned

 $on_value->( $value )

on_error => CODE

Optional. Callback function to invoke when an error is returned. The client's default will apply if not provided.

 $on_error->( $error )

$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( %args )

Sets the value of the property in the server object. Optionally invokes a callback function when complete.

Takes the following named arguments

property => STRING

The name of the property

value => SCALAR

New value to set for the property

on_done => CODE

Optional. Callback function to invoke once the new value is set.

 $on_done->()

on_error => CODE

Optional. Callback function to invoke when an error is returned. The client's default will apply if not provided.

 $on_error->( $error )

$proxy->watch_property( %args )

Watches the given property on the server object, installing callback functions which will be invoked whenever the property value changes.

Takes the following named arguments:

property => STRING

Name of the property

want_initial => BOOLEAN

Optional. If true, requests that the server send the current value of the property at the time the watch is installed, in an on_set event. This is performed atomically with installing watch.

iter_from => INT

Optional. If defined, requests that the server create an iterator for the property value (whose dimension must be a queue). Its 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 object will be returned to the on_iter callback. The iterator is constructed atomically with installing the watch.

This option is mutually-exclusive with want_initial.

on_watched => CODE

Optional. Callback function to invoke once the property watch is successfully installed by the server.

 $on_watched->()

If this is provided, it is guaranteed to be invoked before any invocation of the value change handlers.

on_updated => CODE

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.

on_iter => CODE

Callback function to invoke when the iterator object is returned by the server. This must be provided if iter_from is provided. It is passed the iterator object, and the first and last indices that the iterator will yield (inclusive).

 $on_iter->( $iter, $first_idx, $last_idx )

on_error => CODE

Optional. Callback function to invoke when an error is returned. The client's default will apply if not provided.

 $on_error->( $error )

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.

$proxy->unwatch_property( %args )

Removes a property watches on the given property on the server object that was previously installed using watch_property.

Takes the following named arguments:

property => STRING

Name of the property

ITERATOR METHODS

The following methods are availilable on the property iterator objects given to the on_iter callback of a watch_property method.

$iter->next_forward( %args )

$iter->next_backward( %args )

Requests the next items from the iterator. next_forward moves forwards towards higher-numbered indices, and next_backward moves backwards towards lower-numbered indices.

The following arguments are recognised:

count => INT

Optional. Gives the number of elements requested. Will default to 1 if not provided.

on_more => CODE

Callback to invoke when the new elements are returned. This will be invoked with 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.

 $on_more->( $index, @items )

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm Tangence

perl -MCPAN -e shell
install Tangence