/usr/share/gtk-doc/html/libbonobo/refcounting.html is in libbonobo2-dev 2.32.1-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Reference Counting</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Libbonobo Reference Manual">
<link rel="up" href="factories.html" title="Objects, Factories, Reference Counting">
<link rel="prev" href="libbonobo-bonobo-shlib-factory.html" title="bonobo-shlib-factory">
<link rel="next" href="property-bags.html" title="Property Bags, Events, Listeners">
<meta name="generator" content="GTK-Doc V1.19 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="libbonobo-bonobo-shlib-factory.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="factories.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Libbonobo Reference Manual</th>
<td><a accesskey="n" href="property-bags.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="refcounting"></a><div class="titlepage"></div>
<div class="refsect1">
<a name="id-1.3.5.2"></a><h2>Reference Counting</h2>
<p>
Bonobo component reference counting, version 0.1
by Michael Meeks <mmeeks@gnu.org>
and Mike Fleming <mfleming@eazel.com>
</p>
<div class="refsect2">
<a name="id-1.3.5.2.3"></a><h3>Bonobo Objects</h3>
<p>
A bonobo object is a glib object that implements an
CORBA interface, it also contains a pointer to the
BonoboAggregateObject that it is part of. A bonobo
object has two reference counts; the first is a
GObject reference count on the object. This should
be 1 at all times except pre-finalization. The main
reference count for the aggregate is stored in
the</p>
<pre class="programlisting">
typedef struct {
int ref_count;
GList *objs;
} BonoboAggregateObject;
</pre>
<p>structure. Also in this structure is a list of all
the objects implementing other interfaces in this
aggregate. Clearly an object is always in its own
aggregate hence:</p>
<pre class="programlisting">
g_assert (g_list_find (object->priv->ao->objs, object) == object);
</pre>
<p>Is always true. The
<em class="structfield"><code>object->priv->ao</code></em>
dereference is merely a nice way of encapsulating this
information inside
<code class="filename">bonobo-object.c</code> and ensuring that
it can't be fiddled with elsewhere.</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.3.5.2.4"></a><h3>Ref counting</h3>
<p> The only ref count to manipulate is that on the
aggregate obejct, this is done via the
<code class="function">bonobo_object_ref / unref</code> pair,
it is also done remotely via the
<code class="function">Bonobo_Object_ref / unref</code> CORBA
stubs. There is no 'destroy' method, if you want this
method you are probably confused about how GObject
deals with allocation.</p>
<p>
Some people try to use <code class="function">g_object_ref /
unref</code> on
<code class="classname">BonoboObjects</code>; sadly this will
cause very serious grief. This if you
<code class="function">g_object_unref</code> a bonobo object,
then that object will be destroyed without consulting
the aggregate ref-count, and without sorting out the
aggregate. The net effect of this is that the
aggregate is left including a finalized object. This
is a very bad move indeed.</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.3.5.2.5"></a><h3>Reference leaks</h3>
<p>
Catching reference leaks is evily difficult. The first
approach is to set environment variable
<code class="envar">BONOBO_DEBUG_FLAGS</code> to a colon separated
list of a subset of {object, running, aggregate,
lifecycle, refs}. This will enable debugging output in
certain parts of libbonobo. The output will be written
to stdout or, alternatively, if you set
<code class="envar">BONOBO_DEBUG_DIR</code> to a directory path,
to a file named
<code class="filename">bonobo-debug-<pid></code> in that
directory. This combined with a call to
<code class="function">bonobo_shutdown ()</code> before exiting
your program should provide a dump of all object
references floating in your code.</p>
<p>Another good way of catching leaks---having guessed
which object is not getting freed---is to fire up
container and component in gdb, break in
eg. bonobo_embeddable_new and insert a hardware watch
point on the ref count [ see also <a class="xref" href="debugging.html" title="Debugging"><span class="refentrytitle">Debugging</span></a> ]:</p>
<pre class="programlisting">
(gdb) p &((BonoboObject *)embeddable)->priv->ao->ref_count
$N = (int *) 0x80808102
(gdb) watch *0x80808102
(gdb) cont
</pre>
<p>
This will result in gdb giving you control each time
the ref count is changed. At this point halt the other
end of the CORBA link and start logging traces at both
ends. By the time the program exits you should have
worked out where the reference went astray.</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.3.5.2.6"></a><h3>Ref Counting Conventions</h3>
<p>And now for the important stuff:</p>
<div class="refsect3">
<a name="id-1.3.5.2.6.3"></a><h4>Bonobo Ref Counting</h4>
<p>The Bonobo ref count convention is as follows.
(Mild rewording; same meaning as before)</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem"><p> A function returning an object,
either as the return value or by-reference,
must always add a reference before returning.
(Alternately: the callee must create a
reference to the returned object that the
caller owns)</p></li>
<li class="listitem"><p> A function that accepts a bonobo
object as an in/out parameter must unreference
the originally passed object once if the
function wishes to change the value of the
in/out parameter. (The function must ref()
new objects returned via this in/out in
accordance with [1]) </p></li>
<li class="listitem"><p> An object passed into a function
needs only be ref()'d if the ifunction wishes
to retain a reference to the object beyond the
scope of the function call.</p></li>
</ol></div>
<p>In addition, there's a consensus that interface
designers should be advised against designing
methods with in/out parameters. In/out parameters
can obscure the lifetime of the passed argument to
casual code observers, and thus may cause hidden
side-effects.</p>
</div>
<div class="refsect3">
<a name="id-1.3.5.2.6.4"></a><h4>CORBA Ref-counting</h4>
<p>Since the ORB also maintains reference counts
per interface handle, should you be returning a
reference to an object it is imperative to</p>
<pre class="programlisting">
Bonobo_Unknown_ref (corba_object, ev);
return CORBA_Object_duplicate (corba_object, ev);
</pre>
<p> To assist with this there are two functions:</p>
<pre class="synopsis">
Bonobo_Unknown bonobo_object_dup_ref (Bonobo_Unknown object,
CORBA_Environment *ev);
void bonobo_object_release_unref (Bonobo_Unknown object,
CORBA_Environment *ev);
</pre>
<p>
So to return an Unknown from a impl you can simply:</p>
<pre class="programlisting">
return bonobo_object_dup_ref (corba_object, ev);</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p>there is a caveat with this approach which is this:</p>
<p>If you construct a BonoboObject in an impl_
whose reference you wish to hand back to the
caller then the situation is slightly
different. In this case you have an object
with the following:</p>
<p>Bonobo_Unknown: ref 1</p>
<p>BonoboObject: ref 1</p>
<p>
You want to hand a CORBA reference to this
object to the client, without incrementing the
BonoboObject reference. To do this you must
do:</p>
<pre class="programlisting">
return CORBA_Object_duplicate (BONOBO_OBJREF (myobject));
</pre>
<p>The mirror of this is that if you want to
hand a ref to an impl you will need to
CORBA_Object_duplicate the value before
inserting it into a BonoboObjectClient.</p>
</div>
</div>
<div class="refsect3">
<a name="id-1.3.5.2.6.5"></a><h4>Ref counting and one-way methods</h4>
<p>While the ORB has built in support for correct
referencing on 1 way methods, the Bonobo reference
count does not; hence if you wish to hand a bonobo
reference to several listeners you need to do
something like:</p>
<pre class="programlisting">
ref = Bonobo_Unknown_ref (BONOBO_OBJREF (obj), ev);
Bonobo_Sample_executeOnewayMethod (foo, ref, ev);
</pre>
<p>And at the other end in executeOnewayMethod the
reference needs to be released.</p>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.19</div>
</body>
</html>
|