.\" 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::Object 3pm"
.TH Tangence::Object 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::Object" \- base class for accessible objects in a "Tangence" server
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class acts as a base class for the accessible objects in a Tangence
server. All the objects actually created and made accessible to clients will
be subclasses of this one, including internally-created objects such as
Tangence::Registry.
.PP
These objects are not directly constructed by calling the \f(CW\*(C`new\*(C'\fR class method;
instead the \f(CW\*(C`Tangence::Registry\*(C'\fR should be used to construct one.
.SH "METHODS"
.IX Header "METHODS"
.SS "destroy"
.IX Subsection "destroy"
.Vb 1
\&   $obj\->destroy
.Ve
.PP
Requests that the object destroy itself, informing all clients that are aware
of it. Once they all report that they have dropped the object, the object is
deconstructed for real.
.PP
Not to be confused with Perl's own \f(CW\*(C`DESTROY\*(C'\fR method.
.SS "id"
.IX Subsection "id"
.Vb 1
\&   $id = $obj\->id
.Ve
.PP
Returns the object's \f(CW\*(C`Tangence\*(C'\fR \s-1ID\s0 number
.SS "describe"
.IX Subsection "describe"
.Vb 1
\&   $description = $obj\->describe
.Ve
.PP
Returns a textual description of the object, for internal debugging purposes.
Subclasses are encouraged to override this method to return something more
descriptive within their domain of interest
.SS "registry"
.IX Subsection "registry"
.Vb 1
\&   $registry = $obj\->registry
.Ve
.PP
Returns the Tangence::Registry that constructed this object.
.SS "class"
.IX Subsection "class"
.Vb 1
\&   $class = $obj\->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 = $obj\->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 = $obj\->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 = $obj\->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 "fire_event"
.IX Subsection "fire_event"
.Vb 1
\&   $obj\->fire_event( $event, @args )
.Ve
.PP
Fires the named event on the object. Each event subscription function will be
invoked with the given arguments.
.SS "subscribe_event"
.IX Subsection "subscribe_event"
.Vb 1
\&   $id = $obj\->subscribe_event( $event, $callback )
.Ve
.PP
Subscribes an event-handling callback \s-1CODE\s0 ref to the named event. When the
event is fired by \f(CW\*(C`fire_event\*(C'\fR this callback will be invoked, being passed
the object reference and the event's arguments.
.PP
.Vb 1
\& $callback\->( $obj, @args )
.Ve
.PP
Returns an opaque \s-1ID\s0 value that can be used to remove this subscription by
calling \f(CW\*(C`unsubscribe_event\*(C'\fR.
.SS "unsubscribe_event"
.IX Subsection "unsubscribe_event"
.Vb 1
\&   $obj\->unsubscribe_event( $event, $id )
.Ve
.PP
Removes an event-handling callback previously registered with
\&\f(CW\*(C`subscribe_event\*(C'\fR.
.SS "watch_property"
.IX Subsection "watch_property"
.Vb 1
\&   $id = $obj\->watch_property( $prop, %callbacks )
.Ve
.PP
Watches a named property for changes, registering a set of callback functions
to be invoked when the property changes in certain ways. The set of callbacks
required depends on the dimension of the property being watched.
.PP
For all property types:
.PP
.Vb 1
\&   $on_set\->( $obj, $value )
.Ve
.PP
For hash properties:
.PP
.Vb 2
\&   $on_add\->( $obj, $key, $value )
\&   $on_del\->( $obj, $key )
.Ve
.PP
For queue properties:
.PP
.Vb 2
\&   $on_push\->( $obj, @values )
\&   $on_shift\->( $obj, $count )
.Ve
.PP
For array properties:
.PP
.Vb 4
\&   $on_push\->( $obj, @values )
\&   $on_shift\->( $obj, $count )
\&   $on_splice\->( $obj, $index, $count, @values )
\&   $on_move\->( $obj, $index, $delta )
.Ve
.PP
For objset properties:
.PP
.Vb 2
\&   $on_add\->( $obj, $added_object )
\&   $on_del\->( $obj, $deleted_object_id )
.Ve
.PP
Alternatively, a single callback may be installed that is invoked after any
change of the property, being passed the new value entirely:
.PP
.Vb 1
\&   $on_updated\->( $obj, $value )
.Ve
.PP
Returns an opaque \s-1ID\s0 value that can be used to remove this watch by calling
\&\f(CW\*(C`unwatch_property\*(C'\fR.
.SS "unwatch_property"
.IX Subsection "unwatch_property"
.Vb 1
\&   $obj\->unwatch_property( $prop, $id )
.Ve
.PP
Removes the set of callback functions previously registered with
\&\f(CW\*(C`watch_property\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>