Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/python/doc/v2/callbacks.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: 10.8 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
4<!-- Software License, Version 1.0. (See accompanying -->
5<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
6<html>
7  <head>
8    <meta name="generator" content=
9    "HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
10    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
11    <link rel="stylesheet" type="text/css" href="../boost.css">
12
13    <title>Boost.Python - Calling Python Functions and Methods</title>
14  </head>
15
16  <body link="#0000ff" vlink="#800080">
17    <table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
18    "header">
19      <tr>
20        <td valign="top" width="300">
21          <h3><a href="../../../../index.htm"><img height="86" width="277"
22          alt="C++ Boost" src="../../../../boost.png" border="0"></a></h3>
23        </td>
24
25        <td valign="top">
26          <h1 align="center"><a href="../index.html">Boost.Python</a></h1>
27
28          <h2 align="center">Calling Python Functions and Methods</h2>
29        </td>
30      </tr>
31    </table>
32    <hr>
33
34    <h2>Contents</h2>
35
36    <dl class="page-index">
37      <dt><a href="#introduction">Introduction</a></dt>
38
39      <dt><a href="#argument_handling">Argument Handling</a></dt>
40
41      <dt><a href="#result_handling">Result Handling</a></dt>
42
43      <dt><a href="#result_handling">Rationale</a></dt>
44    </dl>
45    <hr>
46
47    <h2><a name="introduction">Introduction</a></h2>
48    The simplest way to call a Python function from C++, given an <code><a
49    href="object.html#object-spec">object</a></code> instance <code>f</code>
50    holding the function, is simply to invoke its function call operator.
51<pre>
52f("tea", 4, 2) // In Python: f('tea', 4, 2)
53</pre>
54    And of course, a method of an <code><a href=
55    "object.html#object-spec">object</a></code> instance <code>x</code> can
56    be invoked by using the function-call operator of the corresponding
57    attribute:
58<pre>
59x.attr("tea")(4, 2); // In Python: x.tea(4, 2)
60</pre>
61
62    <p>If you don't have an <code>object</code> instance, Boost.Python
63    provides two families of function templates, <code><a href=
64    "call.html#call-spec">call</a></code> and <code><a href=
65    "call_method.html#call_method-spec">call_method</a></code>, for invoking
66    Python functions and methods respectively on <code>PyObject*</code>s. The
67    interface for calling a Python function object (or any Python callable
68    object) looks like:</p>
69<pre>
70call&lt;ResultType&gt;(callable_object, a1, a2... a<i>N</i>);
71</pre>
72    Calling a method of a Python object is similarly easy:
73<pre>
74call_method&lt;ResultType&gt;(self_object, "<i>method-name</i>", a1, a2... a<i>N</i>);
75</pre>
76    This comparitively low-level interface is the one you'll use when
77    implementing C++ virtual functions that can be overridden in Python.
78
79    <h2><a name="argument_handling">Argument Handling</a></h2>
80
81    <p>Arguments are converted to Python according to their type. By default,
82    the arguments <code>a1</code>...<code>a<i>N</i></code> are copied into
83    new Python objects, but this behavior can be overridden by the use of
84    <code><a href="ptr.html#ptr-spec">ptr()</a></code> and <a href=
85    "../../../bind/ref.html">ref()</a>:</p>
86<pre>
87class X : boost::noncopyable
88{
89   ...
90};
91
92void apply(PyObject* callable, X&amp; x)
93{
94   // Invoke callable, passing a Python object which holds a reference to x
95   boost::python::call&lt;void&gt;(callable, boost::ref(x));
96}
97</pre>
98    In the table below, <code><b>x</b></code> denotes the actual argument
99    object and <code><b>cv</b></code> denotes an optional
100    <i>cv-qualification</i>: "<code>const</code>", "<code>volatile</code>",
101    or "<code>const volatile</code>".
102
103    <table border="1" summary="class_ template parameters">
104      <tr>
105        <th>Argument Type</th>
106
107        <th>Behavior</th>
108      </tr>
109
110      <tr>
111        <td><code>T cv&amp;</code><br>
112         <code>T cv</code></td>
113
114        <td>The Python argument is created by the same means used for the
115        return value of a wrapped C++ function returning <code>T</code>. When
116        <code>T</code> is a class type, that normally means <code>*x</code>
117        is copy-constructed into the new Python object.</td>
118      </tr>
119
120      <tr>
121        <td><code>T*</code></td>
122
123        <td>If <code>x&nbsp;==&nbsp;0</code>, the Python argument will be
124        <code><a href=
125        "http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>.
126        Otherwise, the Python argument is created by the same means used for
127        the return value of a wrapped C++ function returning <code>T</code>.
128        When <code>T</code> is a class type, that normally means
129        <code>*x</code> is copy-constructed into the new Python object.</td>
130      </tr>
131
132      <tr>
133        <td><code><a href=
134        "../../../bind/ref.html">boost::reference_wrapper</a>&lt;T&gt;</code></td>
135
136        <td>The Python argument contains a pointer to, rather than a copy of,
137        <code>x.get()</code>. Note: failure to ensure that no Python code
138        holds a reference to the resulting object beyond the lifetime of
139        <code>*x.get()</code> <b>may result in a crash!</b></td>
140      </tr>
141
142      <tr>
143        <td><code><a href=
144        "ptr.html#pointer_wrapper-spec">pointer_wrapper</a>&lt;T&gt;</code></td>
145
146        <td>If <code>x.get()&nbsp;==&nbsp;0</code>, the Python argument will
147        be <code><a href=
148        "http://www.python.org/doc/current/lib/bltin-null-object.html">None</a></code>.
149        Otherwise, the Python argument contains a pointer to, rather than a
150        copy of, <code>*x.get()</code>. Note: failure to ensure that no
151        Python code holds a reference to the resulting object beyond the
152        lifetime of <code>*x.get()</code> <b>may result in a crash!</b></td>
153      </tr>
154    </table>
155
156    <h2><a name="result_handling">Result Handling</a></h2>
157    In general, <code>call&lt;ResultType&gt;()</code> and
158    <code>call_method&lt;ResultType&gt;()</code> return
159    <code>ResultType</code> by exploiting all lvalue and rvalue
160    <code>from_python</code> converters registered for ResultType and
161    returning a copy of the result. However, when <code>ResultType</code> is
162    a pointer or reference type, Boost.Python searches only for lvalue
163    converters. To prevent dangling pointers and references, an exception
164    will be thrown if the Python result object has only a single reference
165    count.
166
167    <h2><a name="rationale">Rationale</a></h2>
168    In general, to get Python arguments corresponding to
169    <code>a1</code>...<code>a<i>N</i></code>, a new Python object must be
170    created for each one; should the C++ object be copied into that Python
171    object, or should the Python object simply hold a reference/pointer to
172    the C++ object? In general, the latter approach is unsafe, since the
173    called function may store a reference to the Python object somewhere. If
174    the Python object is used after the C++ object is destroyed, we'll crash
175    Python.
176
177    <p>In keeping with the philosophy that users on the Python side shouldn't
178    have to worry about crashing the interpreter, the default behavior is to
179    copy the C++ object, and to allow a non-copying behavior only if the user
180    writes <code><a href="../../../bind/ref.html">boost::ref</a>(a1)</code>
181    instead of a1 directly. At least this way, the user doesn't get dangerous
182    behavior "by accident". It's also worth noting that the non-copying
183    ("by-reference") behavior is in general only available for class types,
184    and will fail at runtime with a Python exception if used otherwise[<a
185    href="#1">1</a>].</p>
186
187    <p>However, pointer types present a problem: one approach is to refuse to
188    compile if any aN has pointer type: after all, a user can always pass
189    <code>*aN</code> to pass "by-value" or <code>ref(*aN)</code> to indicate
190    a pass-by-reference behavior. However, this creates a problem for the
191    expected null pointer to <code>None</code> conversion: it's illegal to
192    dereference a null pointer value.</p>
193
194    <p>The compromise I've settled on is this:</p>
195
196    <ol>
197      <li>The default behavior is pass-by-value. If you pass a non-null
198      pointer, the pointee is copied into a new Python object; otherwise the
199      corresponding Python argument will be None.</li>
200
201      <li>if you want by-reference behavior, use <code>ptr(aN)</code> if
202      <code>aN</code> is a pointer and <code>ref(aN)</code> otherwise. If a
203      null pointer is passed to <code>ptr(aN)</code>, the corresponding
204      Python argument will be <code>None</code>.</li>
205    </ol>
206
207    <p>As for results, we have a similar problem: if <code>ResultType</code>
208    is allowed to be a pointer or reference type, the lifetime of the object
209    it refers to is probably being managed by a Python object. When that
210    Python object is destroyed, our pointer dangles. The problem is
211    particularly bad when the <code>ResultType</code> is char const* - the
212    corresponding Python String object is typically uniquely-referenced,
213    meaning that the pointer dangles as soon as <code>call&lt;char
214    const*&gt;(...)</code> returns.</p>
215
216    <p>The old Boost.Python v1 deals with this issue by refusing to compile
217    any uses of <code>call&lt;char const*&gt;()</code>, but this goes both
218    too far and not far enough. It goes too far because there are cases where
219    the owning Python string object survives beyond the call (just for
220    instance, when it's the name of a Python class), and it goes not far
221    enough because we might just as well have the same problem with a
222    returned pointer or reference of any other type.</p>
223
224    <p>In Boost.Python v2 this is dealt with by:</p>
225
226    <ol>
227      <li>lifting the compile-time restriction on const char* callback
228      returns</li>
229
230      <li>detecting the case when the reference count on the result Python
231      object is 1 and throwing an exception inside of
232      <code>call&lt;U&gt;(...)</code> when <code>U</code> is a pointer or
233      reference type.</li>
234    </ol>
235    This should be acceptably safe because users have to explicitly specify a
236    pointer/reference for <code>U</code> in <code>call&lt;U&gt;</code>, and
237    they will be protected against dangles at runtime, at least long enough
238    to get out of the <code>call&lt;U&gt;(...)</code> invocation.
239    <hr>
240    <a name="1">[1]</a> It would be possible to make it fail at compile-time
241    for non-class types such as int and char, but I'm not sure it's a good
242    idea to impose this restriction yet.
243
244    <p>Revised
245    <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
246  13 November, 2002
247  <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
248    </p>
249
250    <p><i>&copy; Copyright <a href=
251    "../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002.</i></p>
252  </body>
253</html>
254
Note: See TracBrowser for help on using the repository browser.