-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathownership.html
181 lines (169 loc) · 9.76 KB
/
ownership.html
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>2. Ownership Management — API Extractor documentation</title>
<link rel="stylesheet" href="_static/pysidedocs.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="API Extractor documentation" href="index.html" />
<link rel="next" title="3. The API Extractor Type System" href="typesystem.html" />
<link rel="prev" title="1. API Extractor Overview" href="overview.html" />
</head>
<body>
<div id="container">
<div class="header">
<div class="header_container">
<div class="logo"><a href="https://pyside.github.io"><img alt="PySide" src="_static/pysidelogo.png" width="199" height="102" /></a></div>
<div class="related">
<ul>
<li><a href="index.html">API Extractor documentation</a></li>
</ul>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">2. Ownership Management</a><ul>
<li><a class="reference internal" href="#ownership-transfers">2.1. Ownership transfers</a><ul>
<li><a class="reference internal" href="#from-c-to-target">2.1.1. From C++ to target</a></li>
<li><a class="reference internal" href="#from-target-to-c">2.1.2. From target to C++</a></li>
</ul>
</li>
<li><a class="reference internal" href="#parent-child-relationship">2.2. Parent-child relationship</a></li>
<li><a class="reference internal" href="#invalidation-after-use">2.3. Invalidation after use</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="overview.html"
title="previous chapter">1. API Extractor Overview</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="typesystem.html"
title="next chapter">3. The API Extractor Type System</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" id="q" size="18" />
<input type="submit" value="Go" id="search_button" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="ownership-management">
<h1>2. Ownership Management<a class="headerlink" href="#ownership-management" title="Permalink to this headline">¶</a></h1>
<p>Among the various types of instances interactions, sometimes an object
may be <em>owned</em> by another object, so that the owner is responsible for
destroying the owned object, like in Qt’s object system <a class="footnote-reference" href="#id2" id="id1">[1]</a>.
This kind of relationship has a big role on interfacing with the target language, like
with Python’s reference counting.</p>
<div class="section" id="ownership-transfers">
<h2>2.1. Ownership transfers<a class="headerlink" href="#ownership-transfers" title="Permalink to this headline">¶</a></h2>
<div class="section" id="from-c-to-target">
<h3>2.1.1. From C++ to target<a class="headerlink" href="#from-c-to-target" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><p>When an object that is currently owned by C++ has its ownership transfered
back to the target language, the binding can know for sure when the object will be deleted and
tie the C++ instance existence to the wrapper, calling the C++ destructor normally when the
wrapper is deleted.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument</span> <span class="na">index=</span><span class="s">"1"</span><span class="nt">></span>
<span class="nt"><define-ownership</span> <span class="na">class=</span><span class="s">"target"</span> <span class="na">owner=</span><span class="s">"target"</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="from-target-to-c">
<h3>2.1.2. From target to C++<a class="headerlink" href="#from-target-to-c" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><p>In the opposite direction,when an object ownership is transfered from the target language
to C++, the native code takes full control of the object life and you don’t
know when that object will be deleted, rendering the wrapper object invalid,
unless you’re wrapping an object with a virtual destructor,
so you can override it and be notified of its destruction.</p>
<p>By default it’s safer to just render the wrapper
object invalid and raise some error if the user tries to access
one of this objects members or pass it as argument to some function, to avoid unpleasant segfaults.
Also you should avoid calling the C++ destructor when deleting the wrapper.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument</span> <span class="na">index=</span><span class="s">"1"</span><span class="nt">></span>
<span class="nt"><define-ownership</span> <span class="na">class=</span><span class="s">"target"</span> <span class="na">owner=</span><span class="s">"c++"</span> <span class="nt">/></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
</div></blockquote>
</div>
</div>
<div class="section" id="parent-child-relationship">
<h2>2.2. Parent-child relationship<a class="headerlink" href="#parent-child-relationship" title="Permalink to this headline">¶</a></h2>
<p>One special type of relationship is the parent-child. When an object is called
the parent of another object (the child), the former is in charge of deleting its
child when deleted and the target language can trust that the child will be alive
as long as the parent is, unless some other method can take the C++ ownership away from the parent.</p>
<p>One of the main uses of this scheme is Qt’s object system, with ownership among QObject-derived
classes, creating “trees” of instances.</p>
<blockquote>
<div><div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument</span> <span class="na">index=</span><span class="s">"this"</span><span class="nt">></span>
<span class="nt"><parent</span> <span class="na">index=</span><span class="s">"1"</span> <span class="na">action=</span><span class="s">"add"</span><span class="nt">></span>
<span class="nt"></modify-argument></span>
</pre></div>
</div>
</div></blockquote>
<p>In this example, the instance with the method that is being invoked (indicated by ‘index=”this”’ on
modify-argument) will be marked as a child
of the first argument using the <cite>parent</cite> tag. To remove ownership, just use “remove” in the action attribute. <strong>Removing
parentship also transfers the ownership back to python.</strong></p>
</div>
<div class="section" id="invalidation-after-use">
<h2>2.3. Invalidation after use<a class="headerlink" href="#invalidation-after-use" title="Permalink to this headline">¶</a></h2>
<p>Sometimes an object is created as a virtual method call argument and destroyed after the
call returned. In this case, you should use the <tt class="docutils literal"><span class="pre">invalidate-after-use</span></tt> attribute in the
<tt class="docutils literal"><span class="pre">modify-argument</span></tt> tag to mark the wrapper as invalid right after the virtual method returns.</p>
<blockquote>
<div><div class="highlight-xml"><div class="highlight"><pre><span class="nt"><modify-argument</span> <span class="na">index=</span><span class="s">"2"</span> <span class="na">invalidate-after-use=</span><span class="s">"yes"</span><span class="nt">/></span>
</pre></div>
</div>
</div></blockquote>
<p>In this example the second argument will be invalidated after this method call.</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>See <em>Object Trees and Object Ownership</em> <a class="reference external" href="http://doc.trolltech.com/4.5/objecttrees.html">http://doc.trolltech.com/4.5/objecttrees.html</a></td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
<a href="http://www.indt.org.br"><img src="_static/logo_indt.jpg" alt="Indt" border="0" /></a>
<a href="http://www.openbossa.org"><img src="_static/logo_openbossa.png" alt="Openbossa" border="0" /></a>
<a href="http://qt.nokia.com/"><img src="_static/logo_qt.png" alt="Qt" border="0" /></a>
<a href="http://www.python.org"><img src="_static/logo_python.jpg" alt="Python" border="0" /></a>
</div>
</div>
</body>
</html>