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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
|
<!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 - Calling Python Functions and Methods</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">Calling Python Functions and Methods</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#argument_handling">Argument Handling</a></dt>
<dt><a href="#result_handling">Result Handling</a></dt>
<dt><a href="#result_handling">Rationale</a></dt>
</dl>
<hr>
<h2><a name="introduction">Introduction</a></h2>
The simplest way to call a Python function from C++, given an <code><a
href="object.html#object-spec">object</a></code> instance <code>f</code>
holding the function, is simply to invoke its function call operator.
<pre>
f("tea", 4, 2) // In Python: f('tea', 4, 2)
</pre>
And of course, a method of an <code><a href=
"object.html#object-spec">object</a></code> instance <code>x</code> can
be invoked by using the function-call operator of the corresponding
attribute:
<pre>
x.attr("tea")(4, 2); // In Python: x.tea(4, 2)
</pre>
<p>If you don't have an <code>object</code> instance, Boost.Python
provides two families of function templates, <code><a href=
"call.html#call-spec">call</a></code> and <code><a href=
"call_method.html#call_method-spec">call_method</a></code>, for invoking
Python functions and methods respectively on <code>PyObject*</code>s. The
interface for calling a Python function object (or any Python callable
object) looks like:</p>
<pre>
call<ResultType>(callable_object, a1, a2... a<i>N</i>);
</pre>
Calling a method of a Python object is similarly easy:
<pre>
call_method<ResultType>(self_object, "<i>method-name</i>", a1, a2... a<i>N</i>);
</pre>
This comparitively low-level interface is the one you'll use when
implementing C++ virtual functions that can be overridden in Python.
<h2><a name="argument_handling">Argument Handling</a></h2>
<p>Arguments are converted to Python according to their type. By default,
the arguments <code>a1</code>...<code>a<i>N</i></code> are copied into
new Python objects, but this behavior can be overridden by the use of
<code><a href="ptr.html#ptr-spec">ptr()</a></code> and <a href=
"../../../bind/ref.html">ref()</a>:</p>
<pre>
class X : boost::noncopyable
{
...
};
void apply(PyObject* callable, X& x)
{
// Invoke callable, passing a Python object which holds a reference to x
boost::python::call<void>(callable, boost::ref(x));
}
</pre>
In the table below, <code><b>x</b></code> denotes the actual argument
object and <code><b>cv</b></code> denotes an optional
<i>cv-qualification</i>: "<code>const</code>", "<code>volatile</code>",
or "<code>const volatile</code>".
<table border="1" summary="class_ template parameters">
<tr>
<th>Argument Type</th>
<th>Behavior</th>
</tr>
<tr>
<td><code>T cv&</code><br>
<code>T cv</code></td>
<td>The Python argument is created by the same means used for the
return value of a wrapped C++ function returning <code>T</code>. When
<code>T</code> is a class type, that normally means <code>*x</code>
is copy-constructed into the new Python object.</td>
</tr>
<tr>
<td><code>T*</code></td>
<td>If <code>x == 0</code>, the Python argument will be
<code><a href=
"http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>.
Otherwise, the Python argument is created by the same means used for
the return value of a wrapped C++ function returning <code>T</code>.
When <code>T</code> is a class type, that normally means
<code>*x</code> is copy-constructed into the new Python object.</td>
</tr>
<tr>
<td><code><a href=
"../../../bind/ref.html">boost::reference_wrapper</a><T></code></td>
<td>The Python argument contains a pointer to, rather than a copy of,
<code>x.get()</code>. Note: failure to ensure that no Python code
holds a reference to the resulting object beyond the lifetime of
<code>*x.get()</code> <b>may result in a crash!</b></td>
</tr>
<tr>
<td><code><a href=
"ptr.html#pointer_wrapper-spec">pointer_wrapper</a><T></code></td>
<td>If <code>x.get() == 0</code>, the Python argument will
be <code><a href=
"http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>.
Otherwise, the Python argument contains a pointer to, rather than a
copy of, <code>*x.get()</code>. Note: failure to ensure that no
Python code holds a reference to the resulting object beyond the
lifetime of <code>*x.get()</code> <b>may result in a crash!</b></td>
</tr>
</table>
<h2><a name="result_handling">Result Handling</a></h2>
In general, <code>call<ResultType>()</code> and
<code>call_method<ResultType>()</code> return
<code>ResultType</code> by exploiting all lvalue and rvalue
<code>from_python</code> converters registered for ResultType and
returning a copy of the result. However, when <code>ResultType</code> is
a pointer or reference type, Boost.Python searches only for lvalue
converters. To prevent dangling pointers and references, an exception
will be thrown if the Python result object has only a single reference
count.
<h2><a name="rationale">Rationale</a></h2>
In general, to get Python arguments corresponding to
<code>a1</code>...<code>a<i>N</i></code>, a new Python object must be
created for each one; should the C++ object be copied into that Python
object, or should the Python object simply hold a reference/pointer to
the C++ object? In general, the latter approach is unsafe, since the
called function may store a reference to the Python object somewhere. If
the Python object is used after the C++ object is destroyed, we'll crash
Python.
<p>In keeping with the philosophy that users on the Python side shouldn't
have to worry about crashing the interpreter, the default behavior is to
copy the C++ object, and to allow a non-copying behavior only if the user
writes <code><a href="../../../bind/ref.html">boost::ref</a>(a1)</code>
instead of a1 directly. At least this way, the user doesn't get dangerous
behavior "by accident". It's also worth noting that the non-copying
("by-reference") behavior is in general only available for class types,
and will fail at runtime with a Python exception if used otherwise[<a
href="#1">1</a>].</p>
<p>However, pointer types present a problem: one approach is to refuse to
compile if any aN has pointer type: after all, a user can always pass
<code>*aN</code> to pass "by-value" or <code>ref(*aN)</code> to indicate
a pass-by-reference behavior. However, this creates a problem for the
expected null pointer to <code>None</code> conversion: it's illegal to
dereference a null pointer value.</p>
<p>The compromise I've settled on is this:</p>
<ol>
<li>The default behavior is pass-by-value. If you pass a non-null
pointer, the pointee is copied into a new Python object; otherwise the
corresponding Python argument will be None.</li>
<li>if you want by-reference behavior, use <code>ptr(aN)</code> if
<code>aN</code> is a pointer and <code>ref(aN)</code> otherwise. If a
null pointer is passed to <code>ptr(aN)</code>, the corresponding
Python argument will be <code>None</code>.</li>
</ol>
<p>As for results, we have a similar problem: if <code>ResultType</code>
is allowed to be a pointer or reference type, the lifetime of the object
it refers to is probably being managed by a Python object. When that
Python object is destroyed, our pointer dangles. The problem is
particularly bad when the <code>ResultType</code> is char const* - the
corresponding Python String object is typically uniquely-referenced,
meaning that the pointer dangles as soon as <code>call<char
const*>(...)</code> returns.</p>
<p>The old Boost.Python v1 deals with this issue by refusing to compile
any uses of <code>call<char const*>()</code>, but this goes both
too far and not far enough. It goes too far because there are cases where
the owning Python string object survives beyond the call (just for
instance, when it's the name of a Python class), and it goes not far
enough because we might just as well have the same problem with a
returned pointer or reference of any other type.</p>
<p>In Boost.Python v2 this is dealt with by:</p>
<ol>
<li>lifting the compile-time restriction on const char* callback
returns</li>
<li>detecting the case when the reference count on the result Python
object is 1 and throwing an exception inside of
<code>call<U>(...)</code> when <code>U</code> is a pointer or
reference type.</li>
</ol>
This should be acceptably safe because users have to explicitly specify a
pointer/reference for <code>U</code> in <code>call<U></code>, and
they will be protected against dangles at runtime, at least long enough
to get out of the <code>call<U>(...)</code> invocation.
<hr>
<a name="1">[1]</a> It would be possible to make it fail at compile-time
for non-class types such as int and char, but I'm not sure it's a good
idea to impose this restriction yet.
<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>
</body>
</html>
|
