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

       The following methods documented in an "await" expression return Future instances.

   id
          $id = $proxy->id

       Returns the object ID for the "Tangence" object being proxied for.

   classname
          $classname = $proxy->classname

       Returns the name of the class of the "Tangence" object being proxied for.

   class
          $class = $proxyobj->class

       Returns the Tangence::Meta::Class object representing the class of this object.

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

       Returns the Tangence::Meta::Method object representing the named method, or "undef" if no such method
       exists.

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

       Returns the Tangence::Meta::Event object representing the named event, or "undef" if no such event
       exists.

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

       Returns the Tangence::Meta::Property object representing the named property, or "undef" if no such
       property exists.

   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.

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

       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:

       on_fire => CODE
               Callback function to invoke whenever the event is fired

                  $on_fire->( @args )

               The  returned  "Future"  it  is guaranteed to be completed before any invocation of the "on_fire"
               event handler.

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

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

       Requests the current value of the property from the server object.

   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.

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

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

       Sets the value of the property in the server object.

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

       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.

       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.

   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 an cursor object that can be used to lazily fetch the values stored in it.

       The $from value indicates which end of the queue the cursor should start from; "CUSR_FIRST" to  start  at
       index  0,  or  "CUSR_LAST"  to start at the highest-numbered index. The cursor is created atomically with
       installing the watch.

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

CURSOR METHODS

       The  following  methods  are   availilable   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.

       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 cursor is already at the end.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.36.0                                       2022-12-13                         Tangence::ObjectProxy(3pm)