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