<!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>
