<!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>API Extractor — 2. Ownership Management</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: '0.10.0',
COLLAPSE_MODINDEX: 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>
<!--[if lt IE 7]>
<style media="screen" type="text/css">
#container {
height:100%;
}
</style>
<![endif]-->
<link rel="top" title="API Extractor v0.10.0 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 id="ownership">
<div id="container">
<div id="header">
<div id="header_container">
<div id="logo"><a href="http://www.pyside.org"><img alt="PySide" src="_static/pysidelogo.png" width="199" height="102" /></a></div>
<ul id="relbar">
<li class="right">
<a href="typesystem.html" title="3. The API Extractor Type System"
accesskey="N">next</a></li>
<li class="right">
<a href="overview.html" title="1. API Extractor Overview"
accesskey="P">previous</a> |</li>
<li><a href="contents.html">API Extractor v0.10.0 documentation</a> »</li>
</ul>
</div>
</div>
<div id="body" >
<div id="sidebar">
<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>
<h3>Previous topic</h3>
<p class="topless"><a href="overview.html"
title="previous chapter">1. API Extractor Overview</a></p>
<h3>Next topic</h3>
<p class="topless"><a href="typesystem.html"
title="next chapter">3. The API Extractor Type System</a></p>
<div id="search_box">
<h3>Quick search</h3>
<form action="search.html" method="get">
<input type="text" name="q" id="q" />
<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>
</div>
<div class="section" id="ownership-management">
<h1>2. Ownership Management</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</h2>
<div class="section" id="from-c-to-target">
<h3>2.1.1. From C++ to target</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++</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</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</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> <!-- container -->
<div id="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>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
388a191dbad6b966fd8a7add43a4053b
>
files
>
50
