Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/python/doc/v2/instance_holder.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 6.8 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3
4<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
5<!-- Software License, Version 1.0. (See accompanying -->
6<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
7<html>
8  <head>
9    <meta name="generator" content="HTML Tidy, see www.w3.org">
10    <meta http-equiv="Content-Type" content=
11    "text/html; charset=iso-8859-1">
12    <link rel="stylesheet" type="text/css" href="../boost.css">
13
14    <title>Boost.Python - &lt;boost/python/instance_holder.hpp&gt;</title>
15  </head>
16
17<style type="text/css">
18 p.c4 {font-style: italic}
19 span.c3 {color: #ff0000}
20 h2.c2 {text-align: center}
21 h1.c1 {text-align: center}
22</style>
23
24  <body link="#0000ff" vlink="#800080">
25    <table border="0" cellpadding="7" cellspacing="0" width="100%"
26    summary="header">
27      <tr>
28        <td valign="top" width="300">
29          <h3><a href="../../../../index.htm"><img height="86" width= 
30          "277" alt="C++ Boost" src="../../../../boost.png" border=
31          "0"></a></h3>
32
33        <td valign="top">
34          <h1 class="c1"><a href="../index.html">Boost.Python</a></h1>
35
36          <h2 class="c2">Header &lt;boost/python/instance_holder.hpp&gt;</h2>
37    </table>
38    <hr>
39
40    <h2>Contents</h2>
41
42    <dl class="page-index">
43      <dt><a href="#introduction">Introduction</a>
44
45      <dt><a href="#classes">Classes</a>
46
47      <dd>
48        <dl class="page-index">
49          <dt><a href="#instance_holder-spec">Class
50          <code>instance_holder</code></a>
51
52          <dd>
53            <dl class="page-index">
54              <dt><a href="#instance_holder-spec-synopsis">Class
55              <code>instance_holder</code> synopsis</a>
56
57              <dt><a href="#instance_holder-spec-ctors">Class
58              <code>instance_holder</code> destructor</a>
59
60              <dt><a href="#instance_holder-spec-modifiers">Class
61              <code>instance_holder</code> modifier functions</a>
62
63              <dt><a href="#instance_holder-spec-observers">Class
64              <code>instance_holder</code> observer functions</a>
65            </dl>
66        </dl>
67
68      <dt><a href="#examples">Example</a>
69    </dl>
70    <hr>
71
72    <h2><a name="introduction"></a>Introduction</h2>
73
74    <p><code>&lt;boost/python/instance_holder.hpp&gt;</code> provides
75    <code>class&nbsp;instance_holder</code>, the base class for types
76    which hold C++ instances of wrapped classes.
77
78    <h2><a name="classes"></a>Classes</h2>
79
80    <h3><a name="instance_holder-spec"></a>Class <code>instance_holder</code></h3>
81
82    <p><code>instance_holder</code> is an abstract base class whose
83    concrete derived classes hold C++ class instances within their
84    Python object wrappers. To allow multiple inheritance in Python
85    from C++ class wrappers, each such Python object contains a chain
86    of <code>instance_holder</code>s. When an <code>__init__</code>
87    function for a wrapped C++ class is invoked, a new
88    <code>instance_holder</code> instance is created and installed in
89    the Python object using its <code><a
90    href="#instance_holder-spec-modifiers">install</a></code>()
91    function. Each concrete class derived from
92    <code>instance_holder</code> must provide a <code><a
93    href="#instance_holder-spec-observers">holds</a>()</code>
94    implementation which allows Boost.Python to query it for the
95    type(s) it is holding. In order to support the held type's wrapped
96    constructor(s), the class must also provide constructors that can
97    accept an initial <code>PyObject*</code> argument referring to the
98    owning Python object, and which forward the rest of their
99    arguments to the constructor of the held type. The initial
100    argument is needed to enable virtual function overriding in
101    Python, and may be ignored, depending on the specific
102    <code>instance_holder</code> subclass.
103
104    <h4><a name="instance_holder-spec-synopsis"></a>Class instance_holder
105    synopsis</h4>
106<pre>
107namespace boost { namespace python
108{
109  class instance_holder : <a href="../../../utility/utility.htm#Class_noncopyable">noncopyable</a>
110  {
111   public:
112      // destructor
113      virtual ~instance_holder();
114
115      // instance_holder modifiers
116      void install(PyObject* inst) throw();
117
118      // instance_holder observers
119      virtual void* holds(type_info) = 0;
120  };
121}}
122</pre>
123
124    <h4><a name="instance_holder-spec-ctors">Class <code>instance_holder</code>
125    destructor</a></h4>
126<pre>
127virtual ~instance_holder();
128</pre>
129
130    <dl class="function-semantics">
131      <dt><b>Effects:</b> destroys the object
132    </dl>
133
134    <h4><a name="instance_holder-spec-modifiers">Class
135    <code>instance_holder</code> modifiers</a></h4>
136<pre>
137void install(PyObject* inst) throw();
138</pre>
139
140    <dl class="function-semantics">
141      <dt><b>Requires:</b> <code>inst</code> is a Python instance of a
142      wrapped C++ class type, or is a type derived from a wrapped C++
143      class type.
144      <dt><b>Effects:</b> installs the new instance at the head of the
145      Python object's chain of held instances.
146      <dt><b>Throws:</b> nothing
147    </dl>
148
149    <h4><a name="instance_holder-spec-observers">Class <code>instance_holder</code>
150    observers</a></h4>
151<pre>
152virtual void* holds(type_info x) = 0;
153</pre>
154
155    <dl class="function-semantics">
156      <dt><b>Returns:</b> A pointer to an object of the type described
157      by <code>x</code> if <code>*this</code> contains such an object,
158      0 otherwise.
159    </dl>
160
161    <h2><a name="examples"></a>Example</h2> 
162
163The following is a simplified version of the instance holder template
164used by Boost.Python to wrap classes held by smart pointers:
165<pre>
166template &lt;class SmartPtr, class Value&gt;
167struct pointer_holder : instance_holder
168{
169   // construct from the SmartPtr type
170   pointer_holder(SmartPtr p)
171       :m_p(p)
172
173   // Forwarding constructors for the held type
174   pointer_holder(PyObject*)
175       :m_p(new Value())
176   {
177   }
178
179   template&lt;class A0&gt;
180   pointer_holder(PyObject*,A0 a0)
181       :m_p(new Value(a0))
182   {
183   }
184
185   template&lt;class A0,class A1&gt;
186   pointer_holder(PyObject*,A0 a0,A1 a1)
187       :m_p(new Value(a0,a1))
188   {
189   }
190   ...
191
192 private: // required holder implementation
193   void* holds(type_info dst_t)
194   {
195       // holds an instance of the SmartPtr type...
196       if (dst_t == python::type_id&lt;SmartPtr&gt;())
197           return &amp;this-&gt;m_p;
198
199       // ...and an instance of the SmartPtr's element_type, if the
200       // pointer is non-null
201       return python::type_id&lt;Value&gt;() == dst_t ? &amp;*this-&gt;m_p : 0;
202   }
203
204 private: // data members
205   SmartPtr m_p;
206};
207</pre>
208
209    <p>Revised
210    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
211  13 November, 2002
212  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
213
214
215    <p class="c4">&copy; Copyright <a href= 
216    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.
217
218  </body>
219</html>
Note: See TracBrowser for help on using the repository browser.