mirror of
https://github.com/boostorg/python.git
synced 2026-01-23 05:42:30 +00:00
125 lines
5.0 KiB
HTML
125 lines
5.0 KiB
HTML
<html>
|
|
<head>
|
|
<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="../../../../c++boost.gif" border="0"></a></h3>
|
|
</td>
|
|
<td valign="top">
|
|
<h1 align="center">Boost.Python</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>
|
|
<dl class="page-index">
|
|
<dt><a href="#CallPolicies-concept">CallPolicies Concept</a></dt>
|
|
</dl>
|
|
</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:
|
|
<ol>
|
|
<li> <code>precall</code> - Python argument tuple management before
|
|
the wrapped object is invoked
|
|
<li> <code>result_converter</code> - C++ return value handling
|
|
<li> <code>postcall</code> - Python argument tuple and result
|
|
management after the wrapped object is invoked
|
|
</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.
|
|
|
|
<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>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.
|
|
|
|
<tr>
|
|
<td valign="top"><code>P::result_converter</code></td>
|
|
<td>A model of <a href="ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>.
|
|
<td>An MPL unarymetafunction object used produce the
|
|
"preliminary" result object.
|
|
|
|
<tr>
|
|
<td valign="top"><code>x.postcall(a, r)</code></td>
|
|
<td>convertible to <code>PyObject*</code>
|
|
<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.
|
|
</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 -->
|
|
19 May, 2002
|
|
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
|
</p>
|
|
<p><i>© Copyright <a href="../../../../people/dave_abrahams.htm">Dave
|
|
Abrahams</a> 2002. All Rights Reserved.</i>
|
|
|
|
<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.
|
|
</body>
|
|
</html>
|