mirror of
https://github.com/boostorg/python.git
synced 2026-01-21 05:02:17 +00:00
166 lines
6.5 KiB
HTML
166 lines
6.5 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
|
|
<!-- Software License, Version 1.0. (See accompanying -->
|
|
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
|
|
<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>
|
|
<li><code>extract_return_type</code> - metafunction for extracting the return type from a given signature type sequence</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>
|
|
<tr>
|
|
<td valign="top"><code>P::extract_return_type</code></td>
|
|
|
|
<td>A model of <a href=
|
|
"../../../mpl/doc/refmanual/metafunction.html">Metafunction</a>.</td>
|
|
|
|
<td>An MPL unary <a href=
|
|
"../../../mpl/doc/refmanual/metafunction.html">Metafunction</a> used extract the return type from a given signature. By default it is derived from mpl::front.</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=
|
|
"http://www.boost.org/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>
|
|
|