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