devn00b
/
EQ2EMu


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212
							<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>boost/python/instance_holder.hpp</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Boost.Python Reference Manual">
<link rel="up" href="../utility_and_infrastructure.html" title="Chapter&#160;7.&#160;Utility and Infrastructure">
<link rel="prev" href="../utility_and_infrastructure.html" title="Chapter&#160;7.&#160;Utility and Infrastructure">
<link rel="next" href="boost_python_pointee_hpp.html" title="boost/python/pointee.hpp">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<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>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<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>
<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
        template <code class="computeroutput"><span class="identifier">instance_holder</span></code></a></span></dt>
<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>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<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>
</h3></div></div></div>
<p>
          &lt;boost/python/instance_holder.hpp&gt; provides class <code class="computeroutput"><span class="identifier">instance_holder</span></code>,
          the base class for types which hold C++ instances of wrapped classes.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<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
        template <code class="computeroutput"><span class="identifier">instance_holder</span></code></a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<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
          <code class="computeroutput"><span class="identifier">intance_holder</span></code> destructor</a></span></dt>
<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
          <code class="computeroutput"><span class="identifier">intance_holder</span></code> modifiers</a></span></dt>
<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
          <code class="computeroutput"><span class="identifier">intance_holder</span></code> observers</a></span></dt>
</dl></div>
<p>
          <code class="computeroutput"><span class="identifier">instance_holder</span></code> is an abstract
          base class whose concrete derived classes hold C++ class instances within
          their Python object wrappers. To allow multiple inheritance in Python from
          C++ class wrappers, each such Python object contains a chain of instance_holders.
          When an <code class="computeroutput"><span class="identifier">__init__</span></code> function
          for a wrapped C++ class is invoked, a new <code class="computeroutput"><span class="identifier">instance_holder</span></code>
          instance is created and installed in the Python object using its <code class="computeroutput"><span class="identifier">install</span><span class="special">()</span></code>
          function. Each concrete class derived from <code class="computeroutput"><span class="identifier">instance_holder</span></code>
          must provide a <code class="computeroutput"><span class="identifier">holds</span><span class="special">()</span></code>
          implementation which allows Boost.Python to query it for the type(s) it
          is holding. In order to support the held type's wrapped constructor(s),
          the class must also provide constructors that can accept an initial <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code>
          argument referring to the owning Python object, and which forward the rest
          of their arguments to the constructor of the held type. The initial argument
          is needed to enable virtual function overriding in Python, and may be ignored,
          depending on the specific <code class="computeroutput"><span class="identifier">instance_holder</span></code>
          subclass.
        </p>
<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>
<span class="special">{</span>
  <span class="keyword">class</span> <span class="identifier">instance_holder</span> <span class="special">:</span> <span class="identifier">noncopyable</span>
  <span class="special">{</span>
   <span class="keyword">public</span><span class="special">:</span>
      <span class="comment">// destructor</span>
      <span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">instance_holder</span><span class="special">();</span>

      <span class="comment">// instance_holder modifiers</span>
      <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>

      <span class="comment">// instance_holder observers</span>
      <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>
  <span class="special">};</span>
<span class="special">}}</span>
</pre>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<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
          <code class="computeroutput"><span class="identifier">intance_holder</span></code> destructor</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">virtual</span> <span class="special">~</span><span class="identifier">instance_holder</span><span class="special">();</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Effects</span></dt>
<dd><p>
                  destroys the object
                </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<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
          <code class="computeroutput"><span class="identifier">intance_holder</span></code> modifiers</a>
</h4></div></div></div>
<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>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
                  <code class="computeroutput"><span class="identifier">inst</span></code> is a Python
                  instance of a wrapped C++ class type, or is a type derived from
                  a wrapped C++ class type.
                </p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
                  installs the new instance at the head of the Python object's chain
                  of held instances.
                </p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
                  nothing
                </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<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
          <code class="computeroutput"><span class="identifier">intance_holder</span></code> observers</a>
</h4></div></div></div>
<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>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Returns</span></dt>
<dd><p>
                  A pointer to an object of the type described by <code class="computeroutput"><span class="identifier">x</span></code>
                  if <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>
                  contains such an object, 0 otherwise.
                </p></dd>
</dl>
</div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<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>
</h3></div></div></div>
<p>
          The following is a simplified version of the instance holder template used
          by Boost.Python to wrap classes held by smart pointers:
        </p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</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">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">pointer_holder</span> <span class="special">:</span> <span class="identifier">instance_holder</span>
<span class="special">{</span>
   <span class="comment">// construct from the SmartPtr type</span>
   <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">SmartPtr</span> <span class="identifier">p</span><span class="special">)</span>
       <span class="special">:</span><span class="identifier">m_p</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span>

   <span class="comment">// Forwarding constructors for the held type</span>
   <span class="identifier">pointer_holder</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*)</span>
       <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="special">{</span>
   <span class="special">}</span>

   <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">&gt;</span>
   <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="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="special">{</span>
   <span class="special">}</span>

   <span class="keyword">template</span><span class="special">&lt;</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">&gt;</span>
   <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>
       <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>
   <span class="special">{</span>
   <span class="special">}</span>
   <span class="special">...</span>

 <span class="keyword">private</span><span class="special">:</span> <span class="comment">// required holder implementation</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">dst_t</span><span class="special">)</span>
   <span class="special">{</span>
       <span class="comment">// holds an instance of the SmartPtr type...</span>
       <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">&lt;</span><span class="identifier">SmartPtr</span><span class="special">&gt;())</span>
           <span class="keyword">return</span> <span class="special">&amp;</span><span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">m_p</span><span class="special">;</span>

       <span class="comment">// ...and an instance of the SmartPtr's element_type, if the</span>
       <span class="comment">// pointer is non-null</span>
       <span class="keyword">return</span> <span class="identifier">python</span><span class="special">::</span><span class="identifier">type_id</span><span class="special">&lt;</span><span class="identifier">Value</span><span class="special">&gt;()</span> <span class="special">==</span> <span class="identifier">dst_t</span> <span class="special">?</span> <span class="special">&amp;*</span><span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">m_p</span> <span class="special">:</span> <span class="number">0</span><span class="special">;</span>
   <span class="special">}</span>

 <span class="keyword">private</span><span class="special">:</span> <span class="comment">// data members</span>
   <span class="identifier">SmartPtr</span> <span class="identifier">m_p</span><span class="special">;</span>
<span class="special">};</span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2002-2005, 2015 David Abrahams, Stefan Seefeld<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        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>
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>