Skip to content

Commit ba2f18c

Browse files
dabrahamsdabrahams
committed
Lots of documentation updates, plus the associated code shuffling needed to expose the right things to users
[SVN r13975]
1 parent c928ede commit ba2f18c

40 files changed

+1447
-805
lines changed

‎doc/v2/HolderGenerator.html‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
<html>
2+
<head>
3+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
4+
<link rel="stylesheet" type="text/css" href="../../../boost.css">
5+
<title>Boost.Python - Holder Concept</title>
6+
</head>
7+
<body link="#0000ff" vlink="#800080">
8+
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
9+
"header">
10+
<tr>
11+
<td valign="top" width="300">
12+
<h3><a href="../../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../../c++boost.gif" border="0"></a></h3>
13+
</td>
14+
<td valign="top">
15+
<h1 align="center">Boost.Python</h1>
16+
<h2 align="center">HolderGenerator Concept</h2>
17+
</td>
18+
</tr>
19+
</table>
20+
<hr>
21+
<dl class="page-index">
22+
<dt><a href="#introduction">Introduction</a></dt>
23+
<dt><a href="#concept-requirements">Concept Requirements</a></dt>
24+
<dl class="page-index">
25+
<dt><a href="#HolderGenerator-concept">HolderGenerator Concept</a></dt>
26+
</dl>
27+
</dl>
28+
29+
<h2><a name="introduction"></a>Introduction</h2>
30+
31+
<p>A HolderGenerator is a unary metafunction class which returns types
32+
suitable for holding instances of its argument in a wrapped C++ class
33+
instance.
34+
35+
<h2><a name="concept-requirements"></a>Concept Requirements</h2>
36+
<h3><a name="HolderGenerator-concept"></a>HolderGenerator Concept</h3>
37+
38+
<p>In the table below, <code><b>G</b></code> denotes an type which
39+
models HolderGenerator, and <code><b>X</b></code> denotes a class
40+
type.
41+
42+
<table summary="Holder expressions" border="1" cellpadding="5">
43+
44+
<tr>
45+
<td><b>Expression</b></td>
46+
<td><b>Requirements</b></td>
47+
</tr>
48+
49+
<tr>
50+
<td valign="top"><code>G::apply&lt;X&gt;::type</code></td>
51+
<td>A concrete subclass of <a
52+
href="instance_holder.html#instance_holder-spec">instance_holder</a>
53+
which can hold objects of type <code>X</code>.
54+
</tr>
55+
</table>
56+
57+
<hr>
58+
<p>Revised
59+
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
60+
20 May, 2002
61+
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
62+
</p>
63+
<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
64+
Abrahams</a> 2002. All Rights Reserved.</i>
65+
66+
<p>Permission to copy, use, modify, sell
67+
and distribute this software is granted provided this copyright notice appears
68+
in all copies. This software is provided "as is" without express or implied
69+
warranty, and with no claim as to its suitability for any purpose.
70+
</body>
71+
</html>

‎doc/v2/class.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -319,9 +319,9 @@ <h4><a name="class_-spec-modifiers"></a>Class template <code>class_</code>
319319
<code><a href=
320320
"make_function.html#make_constructor-spec">make_constructor</a>&lt;Args,Holder&gt;(policies)</code>,
321321
respectively, to the Boost.Python extension class being defined under the name
322-
"__init__". <code>Holder</code> is a model of <a
323-
href="Holder.html">Holder</a> which contains the
324-
<code>HeldType</code>. If the extension class
322+
"__init__". <code>Holder</code> is a concrete subclass of <a
323+
href="instance_holder.html#instance_holder-spec">instance_holder</a>
324+
which holds the <code>HeldType</code>. If the extension class
325325
already has an "__init__" attribute, the usual <a
326326
href="http:overloading.html">overloading procedure</a> applies.
327327

‎doc/v2/errors.html‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ <h2>Contents</h2>
2828

2929
<dd>
3030
<dl class="page-index">
31-
<dt><a href="#class-spec">Class <code>error_already_set</code></a>
31+
<dt><a href="#error_already_set-spec">Class <code>error_already_set</code></a>
3232

3333
<dd>
3434
<dl class="page-index">
@@ -44,6 +44,7 @@ <h2>Contents</h2>
4444
<dt><a href="#handle_exception-spec">handle_exception</a>
4545

4646
<dt><a href="#expect_non_null-spec">expect_non_null</a>
47+
<dt><a href="#throw_error_already_set-spec">throw_error_already_set</a>
4748
</dl>
4849

4950
<dt><a href="#examples">Examples</a>
@@ -117,9 +118,7 @@ <h2><a name="functions"></a>Functions</h2>
117118
an enclosing <code>try</code> block.
118119
</dl>
119120
<pre>
120-
<a name="expect_non_null-spec">PyObject* expect_non_null(PyObject* x);</a>
121-
122-
template &lt;class T&gt; T* expect_non_null(T* x);
121+
<a name="expect_non_null-spec">template &lt;class T&gt; T* expect_non_null(T* x);</a>
123122
</pre>
124123

125124
<dl class="expect_non_null-semantics">
@@ -135,6 +134,16 @@ <h2><a name="functions"></a>Functions</h2>
135134
return 0 on error.
136135
</dl>
137136

137+
<pre>
138+
<a name="throw_error_already_set-spec">void throw_error_already_set();</a>
139+
</pre>
140+
141+
<dl class="throw_error_already_set-semantics">
142+
143+
<dt><b>Effects:</b> <code>throw&nbsp;<a href=
144+
"#error_already_set-spec">error_already_set</a>();</code>
145+
</dl>
146+
138147
<h2><a name="examples"></a>Examples</h2>
139148
<pre>
140149
#include &lt;string&gt;

‎doc/v2/instance_holder.html‎

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

‎doc/v2/iterator.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ <h3><a name="iterator-spec"></a>Class Template <code>iterator</code></h3>
9595
<code>C</code> and creates a Python iterator that traverses
9696
[<code>c.begin()</code>,
9797
<code>c.end()</code>). The optional <a
98-
href="CallPolicies.html"><code>CallPolicies</code></a>
98+
href="CallPolicies.html">CallPolicies</a>
9999
<code>P</code> can be used to control how elements are returned
100100
during iteration.
101101

‎doc/v2/make_function.html‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -78,12 +78,17 @@ <h2><a name="functions"></a>Functions</h2>
7878
<a name=
7979
"make_constructor-spec">template &lt;class T, class ArgList, class Generator&gt;
8080
objects::function* make_constructor();</a>
81+
82+
template &lt;class ArgList, class Generator, class Policies&gt;
83+
objects::function* make_constructor(Policies const&amp; policies)
8184
</pre>
8285

8386
<dl class="function-semantics">
84-
<dt><b>Requires:</b> <code>T</code> is a class type. <code>ArgList</code>
85-
is an <a href="../../../mpl/doc/Sequences.html">MPL sequence</a> of C++
86-
argument types (<i>A1, A2,... AN</i>) such that if
87+
<dt><b>Requires:</b> <code>T</code> is a class
88+
type. <code>Policies</code> is a model of <a
89+
href="CallPolicies.html">CallPolicies</a>. <code>ArgList</code>
90+
is an <a href="../../../mpl/doc/Sequences.html">MPL sequence</a>
91+
of C++ argument types (<i>A1, A2,... AN</i>) such that if
8792
<code>a1, a2</code>... <code>aN</code> are objects of type
8893
<i>A1, A2,... AN</i> respectively, the expression <code>new
8994
Generator::apply&lt;T&gt;::type(a1, a2</code>... <code>aN</code>) is
@@ -94,8 +99,12 @@ <h2><a name="functions"></a>Functions</h2>
9499
from Python, expects its first argument to be a Boost.Python extension
95100
class object. It converts its remaining its arguments to C++ and passes
96101
them to the constructor of a dynamically-allocated
97-
<code>Generator::apply&lt;T&gt;::type</code> object. The result is
98-
installed in the extension class object.
102+
<code>Generator::apply&lt;T&gt;::type</code> object, which is
103+
then installed in the extension class object. In the second
104+
form, the <code>policies</code> are applied to the arguments and
105+
result (<a
106+
href="http://www.python.org/doc/current/lib/bltin-null-object.html">None</a>)
107+
of the Python callable object
99108

100109
<dt><b>Returns:</b> The new Python callable object
101110
</dl>

0 commit comments

Comments
 (0)