.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Tangence::ObjectProxy 3pm"
.TH Tangence::ObjectProxy 3pm "2021-04-30" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"Tangence::ObjectProxy" \- proxy for a "Tangence" object in a
"Tangence::Client"
.SH "DESCRIPTION"
.IX Header "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.
.PP
These objects are not directly constructed by calling the \f(CW\*(C`new\*(C'\fR class method;
instead they are returned by methods on Tangence::Client, or by methods on
other \f(CW\*(C`Tangence::ObjectProxy\*(C'\fR instances. Ultimately every object proxy that a
client uses will come from either the proxy to the registry, or the root
object.
.SH "METHODS"
.IX Header "METHODS"
The following methods documented with a trailing call to \f(CW\*(C`\->get\*(C'\fR return
Future instances.
.SS "id"
.IX Subsection "id"
.Vb 1
\&   $id = $proxy\->id
.Ve
.PP
Returns the object \s-1ID\s0 for the \f(CW\*(C`Tangence\*(C'\fR object being proxied for.
.SS "classname"
.IX Subsection "classname"
.Vb 1
\&   $classname = $proxy\->classname
.Ve
.PP
Returns the name of the class of the \f(CW\*(C`Tangence\*(C'\fR object being proxied for.
.SS "class"
.IX Subsection "class"
.Vb 1
\&   $class = $proxyobj\->class
.Ve
.PP
Returns the Tangence::Meta::Class object representing the class of this
object.
.SS "can_method"
.IX Subsection "can_method"
.Vb 1
\&   $method = $proxy\->can_method( $name )
.Ve
.PP
Returns the Tangence::Meta::Method object representing the named method, or
\&\f(CW\*(C`undef\*(C'\fR if no such method exists.
.SS "can_event"
.IX Subsection "can_event"
.Vb 1
\&   $event = $proxy\->can_event( $name )
.Ve
.PP
Returns the Tangence::Meta::Event object representing the named event, or
\&\f(CW\*(C`undef\*(C'\fR if no such event exists.
.SS "can_property"
.IX Subsection "can_property"
.Vb 1
\&   $property = $proxy\->can_property( $name )
.Ve
.PP
Returns the Tangence::Meta::Property object representing the named
property, or \f(CW\*(C`undef\*(C'\fR if no such property exists.
.SS "call_method"
.IX Subsection "call_method"
.Vb 1
\&   $result = $proxy\->call_method( $mname, @args )\->get
.Ve
.PP
Calls the given method on the server object, passing in the given arguments.
Returns a Future that will yield the method's result.
.SS "subscribe_event"
.IX Subsection "subscribe_event"
.Vb 1
\&   $proxy\->subscribe_event( $event, %callbacks )\->get
.Ve
.PP
Subscribes to the given event on the server object, installing a callback
function which will be invoked whenever the event is fired.
.PP
Takes the following named callbacks:
.IP "on_fire => \s-1CODE\s0" 8
.IX Item "on_fire => CODE"
Callback function to invoke whenever the event is fired
.Sp
.Vb 1
\& $on_fire\->( @args )
.Ve
.Sp
The returned \f(CW\*(C`Future\*(C'\fR it is guaranteed to be completed before any invocation
of the \f(CW\*(C`on_fire\*(C'\fR event handler.
.SS "unsubscribe_event"
.IX Subsection "unsubscribe_event"
.Vb 1
\&   $proxy\->unsubscribe_event( $event )
.Ve
.PP
Removes an event subscription on the given event on the server object that was
previously installed using \f(CW\*(C`subscribe_event\*(C'\fR.
.SS "get_property"
.IX Subsection "get_property"
.Vb 1
\&   $value = $proxy\->get_property( $prop )\->get
.Ve
.PP
Requests the current value of the property from the server object.
.SS "get_property_element"
.IX Subsection "get_property_element"
.Vb 1
\&   $value = $proxy\->get_property_element( $property, $index_or_key )\->get
.Ve
.PP
Requests the current value of an element of the property from the server
object.
.SS "prop"
.IX Subsection "prop"
.Vb 1
\&   $value = $proxy\->prop( $property )
.Ve
.PP
Returns the locally-cached value of a smashed property. If the named property
is not a smashed property, an exception is thrown.
.SS "set_property"
.IX Subsection "set_property"
.Vb 1
\&   $proxy\->set_property( $prop, $value )\->get
.Ve
.PP
Sets the value of the property in the server object.
.SS "watch_property"
.IX Subsection "watch_property"
.Vb 1
\&   $proxy\->watch_property( $property, %callbacks )\->get
.Ve
.SS "watch_property_with_initial"
.IX Subsection "watch_property_with_initial"
.Vb 1
\&   $proxy\->watch_property_with_initial( $property, %callbacks )\->get
.Ve
.PP
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 \f(CW\*(C`on_set\*(C'\fR event, atomically when it
installs the update watches.
.PP
Takes the following named arguments:
.IP "on_updated => \s-1CODE\s0" 8
.IX Item "on_updated => CODE"
Optional. Callback function to invoke whenever the property value changes.
.Sp
.Vb 1
\& $on_updated\->( $new_value )
.Ve
.Sp
If not provided, then individual handlers for individual change types must be
provided.
.PP
The set of callback functions that are required depends on the type of the
property. These are documented in the \f(CW\*(C`watch_property\*(C'\fR method of
Tangence::Object.
.SS "watch_property_with_cursor"
.IX Subsection "watch_property_with_cursor"
.Vb 2
\&   ( $cursor, $first_idx, $last_idx ) =
\&      $proxy\->watch_property_with_cursor( $property, $from, %callbacks )\->get
.Ve
.PP
A variant of \f(CW\*(C`watch_property\*(C'\fR 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.
.PP
The \f(CW$from\fR value indicates which end of the queue the cursor should start
from; \f(CW\*(C`CUSR_FIRST\*(C'\fR to start at index 0, or \f(CW\*(C`CUSR_LAST\*(C'\fR to start at the
highest-numbered index. The cursor is created atomically with installing the
watch.
.SS "unwatch_property"
.IX Subsection "unwatch_property"
.Vb 1
\&   $proxy\->unwatch_property( $property )
.Ve
.PP
Removes a property watches on the given property on the server object that was
previously installed using \f(CW\*(C`watch_property\*(C'\fR.
.SH "CURSOR METHODS"
.IX Header "CURSOR METHODS"
The following methods are availilable on the property cursor objects returned
by the \f(CW\*(C`watch_property_with_cursor\*(C'\fR method.
.SS "next_forward"
.IX Subsection "next_forward"
.Vb 1
\&   ( $index, @more ) = $cursor\->next_forward( $count )\->get
.Ve
.SS "next_backward"
.IX Subsection "next_backward"
.Vb 1
\&   ( $index, @more ) = $cursor\->next_backward( $count )\->get
.Ve
.PP
Requests the next items from the cursor. \f(CW\*(C`next_forward\*(C'\fR moves forwards
towards higher-numbered indices, and \f(CW\*(C`next_backward\*(C'\fR moves backwards towards
lower-numbered indices. If \f(CW$count\fR is unspecified, a default of 1 will
apply.
.PP
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>