1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href=../../../../boost.css>
<title>Boost.Python - CallPolicies Concept</title>
</head>
<body link="#0000ff" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<tr>
<td valign="top" width="300">
<h3><a href="../../../../index.htm"><img height="86" width="277"
alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center"><a href="../index.html">Boost.Python</a></h1>
<h2 align="center">CallPolicies Concept</h2>
</td>
</tr>
</table>
<hr>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#composition">CallPolicies Composition</a></dt>
<dt><a href="#concept-requirements">Concept Requirements</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#CallPolicies-concept">CallPolicies Concept</a></dt>
</dl>
</dd>
</dl>
<h2><a name="introduction"></a>Introduction</h2>
<p>Models of the CallPolicies concept are used to specialize the behavior
of Python callable objects generated by Boost.Python to wrapped C++
objects like function and member function pointers, providing three
behaviors:</p>
<ol>
<li><code>precall</code> - Python argument tuple management before the
wrapped object is invoked</li>
<li><code>result_converter</code> - C++ return value handling</li>
<li><code>postcall</code> - Python argument tuple and result management
after the wrapped object is invoked</li>
</ol>
<h2><a name="composition"></a>CallPolicies Composition</h2>
In order to allow the use of multiple models of CallPolicies in the same
callable object, Boost.Python's CallPolicies class templates provide a
chaining interface which allows them to be recursively composed. This
interface takes the form of an optional template parameter,
<code>Base</code> which defaults to <a href=
"default_call_policies.html#default_call_policies-spec"><code>default_call_policies</code></a>.
By convention, the <code>precall</code> function of the <code>Base</code>
is invoked <i>after</i> the <code>precall</code> function supplied by the
outer template, and the <code>postcall</code> function of the
<code>Base</code> is invoked <i>before</i> the <code>postcall</code>
function of the outer template. If a <code>result_converter</code> is
supplied by the outer template, it <i>replaces</i> any
<code>result_converter</code> supplied by the <code>Base</code>. For an
example, see <a href=
"return_internal_reference.html#return_internal_reference-spec"><code>return_internal_reference</code></a>.
<h2><a name="concept-requirements"></a>Concept Requirements</h2>
<h3><a name="CallPolicies-concept"></a>CallPolicies Concept</h3>
<p>In the table below, <code><b>x</b></code> denotes an object whose type
<code><b>P</b></code> is a model of CallPolicies, <code><b>a</b></code>
denotes a <code>PyObject*</code> pointing to a Python argument tuple
object, and <code><b>r</b></code> denotes a <code>PyObject*</code>
referring to a "preliminary" result object.</p>
<table summary="CallPolicies expressions" border="1" cellpadding="5">
<tr>
<td><b>Expression</b></td>
<td><b>Type</b></td>
<td><b>Result/Semantics</b></td>
</tr>
<tr>
<td valign="top"><code>x.precall(a)</code></td>
<td>convertible to <code>bool</code></td>
<td>returns <code>false</code> and <code><a href=
"http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code>
upon failure, <code>true</code> otherwise.</td>
</tr>
<tr>
<td valign="top"><code>P::result_converter</code></td>
<td>A model of <a href=
"ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>.</td>
<td>An MPL unary <a href=
"../../../mpl/doc/refmanual/metafunction-class.html">Metafunction
Class</a> used produce the "preliminary" result object.</td>
</tr>
<tr>
<td valign="top"><code>x.postcall(a, r)</code></td>
<td>convertible to <code>PyObject*</code></td>
<td>0 <code>0</code> and <code><a href=
"http://www.python.org/doc/2.2/api/exceptionHandling.html#l2h-71">PyErr_Occurred</a>() != 0</code>
upon failure. Must "conserve references" even in the event of an
exception. In other words, if <code>r</code> is not returned, its
reference count must be decremented; if another existing object is
returned, its reference count must be incremented.</td>
</tr>
</table>
Models of CallPolicies are required to be <a href=
"../../../utility/CopyConstructible.html">CopyConstructible</a>.
<hr>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
13 November, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
</p>
<p><i>© Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p>
<p>Permission to copy, use, modify, sell and distribute this software is
granted provided this copyright notice appears in all copies. This
software is provided "as is" without express or implied warranty, and
with no claim as to its suitability for any purpose.</p>
</body>
</html>
|
