1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>boost/python/instance_holder.hpp</title> 5<link rel="stylesheet" href="../../boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Boost.Python Reference Manual"> 8<link rel="up" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> 9<link rel="prev" href="../utility_and_infrastructure.html" title="Chapter 7. Utility and Infrastructure"> 10<link rel="next" href="boost_python_pointee_hpp.html" title="boost/python/pointee.hpp"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table> 14<hr> 15<div class="spirit-nav"> 16<a accesskey="p" href="../utility_and_infrastructure.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_pointee_hpp.html"><img src="../../images/next.png" alt="Next"></a> 17</div> 18<div class="section"> 19<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 20<a name="utility_and_infrastructure.boost_python_instance_holder_hpp"></a><a class="link" href="boost_python_instance_holder_hpp.html" title="boost/python/instance_holder.hpp">boost/python/instance_holder.hpp</a> 21</h2></div></div></div> 22<div class="toc"><dl class="toc"> 23<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.introduction">Introduction</a></span></dt> 24<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder">Class 25 template <code class="computeroutput"><span class="identifier">instance_holder</span></code></a></span></dt> 26<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.examples">Examples</a></span></dt> 27</dl></div> 28<div class="section"> 29<div class="titlepage"><div><div><h3 class="title"> 30<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.introduction"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.introduction" title="Introduction">Introduction</a> 31</h3></div></div></div> 32<p> 33 <boost/python/instance_holder.hpp> provides class <code class="computeroutput"><span class="identifier">instance_holder</span></code>, 34 the base class for types which hold C++ instances of wrapped classes. 35 </p> 36</div> 37<div class="section"> 38<div class="titlepage"><div><div><h3 class="title"> 39<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder" title="Class template instance_holder">Class 40 template <code class="computeroutput"><span class="identifier">instance_holder</span></code></a> 41</h3></div></div></div> 42<div class="toc"><dl class="toc"> 43<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_destructor">Class 44 <code class="computeroutput"><span class="identifier">intance_holder</span></code> destructor</a></span></dt> 45<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_modifiers">Class 46 <code class="computeroutput"><span class="identifier">intance_holder</span></code> modifiers</a></span></dt> 47<dt><span class="section"><a href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_observers">Class 48 <code class="computeroutput"><span class="identifier">intance_holder</span></code> observers</a></span></dt> 49</dl></div> 50<p> 51 <code class="computeroutput"><span class="identifier">instance_holder</span></code> is an abstract 52 base class whose concrete derived classes hold C++ class instances within 53 their Python object wrappers. To allow multiple inheritance in Python from 54 C++ class wrappers, each such Python object contains a chain of instance_holders. 55 When an <code class="computeroutput"><span class="identifier">__init__</span></code> function 56 for a wrapped C++ class is invoked, a new <code class="computeroutput"><span class="identifier">instance_holder</span></code> 57 instance is created and installed in the Python object using its <code class="computeroutput"><span class="identifier">install</span><span class="special">()</span></code> 58 function. Each concrete class derived from <code class="computeroutput"><span class="identifier">instance_holder</span></code> 59 must provide a <code class="computeroutput"><span class="identifier">holds</span><span class="special">()</span></code> 60 implementation which allows Boost.Python to query it for the type(s) it 61 is holding. In order to support the held type's wrapped constructor(s), 62 the class must also provide constructors that can accept an initial <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code> 63 argument referring to the owning Python object, and which forward the rest 64 of their arguments to the constructor of the held type. The initial argument 65 is needed to enable virtual function overriding in Python, and may be ignored, 66 depending on the specific <code class="computeroutput"><span class="identifier">instance_holder</span></code> 67 subclass. 68 </p> 69<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span> 70<span class="special">{</span> 71 <span class="keyword">class</span> <span class="identifier">instance_holder</span> <span class="special">:</span> <span class="identifier">noncopyable</span> 72 <span class="special">{</span> 73 <span class="keyword">public</span><span class="special">:</span> 74 <span class="comment">// destructor</span> 75 <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">instance_holder</span><span class="special">();</span> 76 77 <span class="comment">// instance_holder modifiers</span> 78 <span class="keyword">void</span> <span class="identifier">install</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">inst</span><span class="special">)</span> <span class="keyword">throw</span><span class="special">();</span> 79 80 <span class="comment">// instance_holder observers</span> 81 <span class="keyword">virtual</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">holds</span><span class="special">(</span><span class="identifier">type_info</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> 82 <span class="special">};</span> 83<span class="special">}}</span> 84</pre> 85<div class="section"> 86<div class="titlepage"><div><div><h4 class="title"> 87<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_destructor"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_destructor" title="Class intance_holder destructor">Class 88 <code class="computeroutput"><span class="identifier">intance_holder</span></code> destructor</a> 89</h4></div></div></div> 90<pre class="programlisting"><span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">instance_holder</span><span class="special">();</span></pre> 91<div class="variablelist"> 92<p class="title"><b></b></p> 93<dl class="variablelist"> 94<dt><span class="term">Effects</span></dt> 95<dd><p> 96 destroys the object 97 </p></dd> 98</dl> 99</div> 100</div> 101<div class="section"> 102<div class="titlepage"><div><div><h4 class="title"> 103<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_modifiers"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_modifiers" title="Class intance_holder modifiers">Class 104 <code class="computeroutput"><span class="identifier">intance_holder</span></code> modifiers</a> 105</h4></div></div></div> 106<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">install</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">inst</span><span class="special">)</span> <span class="keyword">throw</span><span class="special">();</span></pre> 107<div class="variablelist"> 108<p class="title"><b></b></p> 109<dl class="variablelist"> 110<dt><span class="term">Requires</span></dt> 111<dd><p> 112 <code class="computeroutput"><span class="identifier">inst</span></code> is a Python 113 instance of a wrapped C++ class type, or is a type derived from 114 a wrapped C++ class type. 115 </p></dd> 116<dt><span class="term">Effects</span></dt> 117<dd><p> 118 installs the new instance at the head of the Python object's chain 119 of held instances. 120 </p></dd> 121<dt><span class="term">Throws</span></dt> 122<dd><p> 123 nothing 124 </p></dd> 125</dl> 126</div> 127</div> 128<div class="section"> 129<div class="titlepage"><div><div><h4 class="title"> 130<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_observers"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.class_template_instance_holder.class_intance_holder_observers" title="Class intance_holder observers">Class 131 <code class="computeroutput"><span class="identifier">intance_holder</span></code> observers</a> 132</h4></div></div></div> 133<pre class="programlisting"><span class="keyword">virtual</span> <span class="keyword">void</span> <span class="special">*</span><span class="identifier">holds</span><span class="special">(</span><span class="identifier">type_info</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span></pre> 134<div class="variablelist"> 135<p class="title"><b></b></p> 136<dl class="variablelist"> 137<dt><span class="term">Returns</span></dt> 138<dd><p> 139 A pointer to an object of the type described by <code class="computeroutput"><span class="identifier">x</span></code> 140 if <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code> 141 contains such an object, 0 otherwise. 142 </p></dd> 143</dl> 144</div> 145</div> 146</div> 147<div class="section"> 148<div class="titlepage"><div><div><h3 class="title"> 149<a name="utility_and_infrastructure.boost_python_instance_holder_hpp.examples"></a><a class="link" href="boost_python_instance_holder_hpp.html#utility_and_infrastructure.boost_python_instance_holder_hpp.examples" title="Examples">Examples</a> 150</h3></div></div></div> 151<p> 152 The following is a simplified version of the instance holder template used 153 by Boost.Python to wrap classes held by smart pointers: 154 </p> 155<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">SmartPtr</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Value</span><span class="special">></span> 156<span class="keyword">struct</span> <span class="identifier">pointer_holder</span> <span class="special">:</span> <span class="identifier">instance_holder</span> 157<span class="special">{</span> 158 <span class="comment">// construct from the SmartPtr type</span> 159 <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">SmartPtr</span> <span class="identifier">p</span><span class="special">)</span> 160 <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span> 161 162 <span class="comment">// Forwarding constructors for the held type</span> 163 <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*)</span> 164 <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">Value</span><span class="special">())</span> 165 <span class="special">{</span> 166 <span class="special">}</span> 167 168 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">></span> 169 <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span><span class="identifier">A0</span> <span class="identifier">a0</span><span class="special">)</span> 170 <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">Value</span><span class="special">(</span><span class="identifier">a0</span><span class="special">))</span> 171 <span class="special">{</span> 172 <span class="special">}</span> 173 174 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span> 175 <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span><span class="identifier">A0</span> <span class="identifier">a0</span><span class="special">,</span><span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">)</span> 176 <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">Value</span><span class="special">(</span><span class="identifier">a0</span><span class="special">,</span><span class="identifier">a1</span><span class="special">))</span> 177 <span class="special">{</span> 178 <span class="special">}</span> 179 <span class="special">...</span> 180 181 <span class="keyword">private</span><span class="special">:</span> <span class="comment">// required holder implementation</span> 182 <span class="keyword">void</span><span class="special">*</span> <span class="identifier">holds</span><span class="special">(</span><span class="identifier">type_info</span> <span class="identifier">dst_t</span><span class="special">)</span> 183 <span class="special">{</span> 184 <span class="comment">// holds an instance of the SmartPtr type...</span> 185 <span class="keyword">if</span> <span class="special">(</span><span class="identifier">dst_t</span> <span class="special">==</span> <span class="identifier">python</span><span class="special">::</span><span class="identifier">type_id</span><span class="special"><</span><span class="identifier">SmartPtr</span><span class="special">>())</span> 186 <span class="keyword">return</span> <span class="special">&</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">m_p</span><span class="special">;</span> 187 188 <span class="comment">// ...and an instance of the SmartPtr's element_type, if the</span> 189 <span class="comment">// pointer is non-null</span> 190 <span class="keyword">return</span> <span class="identifier">python</span><span class="special">::</span><span class="identifier">type_id</span><span class="special"><</span><span class="identifier">Value</span><span class="special">>()</span> <span class="special">==</span> <span class="identifier">dst_t</span> <span class="special">?</span> <span class="special">&*</span><span class="keyword">this</span><span class="special">-></span><span class="identifier">m_p</span> <span class="special">:</span> <span class="number">0</span><span class="special">;</span> 191 <span class="special">}</span> 192 193 <span class="keyword">private</span><span class="special">:</span> <span class="comment">// data members</span> 194 <span class="identifier">SmartPtr</span> <span class="identifier">m_p</span><span class="special">;</span> 195<span class="special">};</span> 196</pre> 197</div> 198</div> 199<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 200<td align="left"></td> 201<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p> 202 Distributed under the Boost Software License, Version 1.0. (See accompanying 203 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a> 204 </p> 205</div></td> 206</tr></table> 207<hr> 208<div class="spirit-nav"> 209<a accesskey="p" href="../utility_and_infrastructure.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../utility_and_infrastructure.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="boost_python_pointee_hpp.html"><img src="../../images/next.png" alt="Next"></a> 210</div> 211</body> 212</html> 213
