| <!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 Cygwin (vers 1st February 2003), see www.w3.org"> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <link rel="stylesheet" type="text/css" href="../boost.css"> |
| <title> |
| Boost.Python - <boost/python/with_custodian_and_ward.hpp> |
| </title> |
| </head> |
| <body> |
| <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"> |
| Header <boost/python/with_custodian_and_ward.hpp> |
| </h2> |
| </td> |
| </tr> |
| </table> |
| <hr> |
| <h2> |
| Contents |
| </h2> |
| <dl class="page-index"> |
| <dt> |
| <a href="#introduction">Introduction</a> |
| </dt> |
| <dt> |
| <a href="#classes">Classes</a> |
| </dt> |
| <dd> |
| <dl class="page-index"> |
| <dt> |
| <a href="#with_custodian_and_ward-spec">Class Template |
| <code>with_custodian_and_ward</code></a> |
| </dt> |
| <dd> |
| <dl class="page-index"> |
| <dt> |
| <a href="#with_custodian_and_ward-spec-synopsis">Class |
| Template <code>with_custodian_and_ward</code> synopsis</a> |
| </dt> |
| <dt> |
| <a href="#with_custodian_and_ward-spec-statics">Class |
| <code>with_custodian_and_ward</code> static functions</a> |
| </dt> |
| </dl> |
| </dd> |
| <dt> |
| <a href="#with_custodian_and_ward_postcall-spec">Class Template |
| <code>with_custodian_and_ward_postcall</code></a> |
| </dt> |
| <dd> |
| <dl class="page-index"> |
| <dt> |
| <a href= |
| "#with_custodian_and_ward_postcall-spec-synopsis">Class |
| Template <code>with_custodian_and_ward_postcall</code> |
| synopsis</a> |
| </dt> |
| <dt> |
| <a href= |
| "#with_custodian_and_ward_postcall-spec-statics">Class |
| <code>with_custodian_and_ward_postcall</code> static |
| functions</a> |
| </dt> |
| </dl> |
| </dd> |
| </dl> |
| </dd> |
| <dt> |
| <a href="#examples">Example</a> |
| </dt> |
| </dl> |
| <hr> |
| <h2> |
| <a name="introduction">Introduction</a> |
| </h2>This header provides faciliites for establishing a lifetime |
| dependency between two of a function's Python argument or result objects. |
| The <i>ward</i> object will not be destroyed until after the custodian as |
| long as the <i>custodian</i> object supports <a href= |
| "http://www.python.org/doc/current/lib/module-weakref.html">weak |
| references</a> (Boost.Python extension classes all support weak |
| references). If the <i>custodian</i> object does not support weak |
| references and is not <code>None</code>, an appropriate exception will be |
| thrown. The two class templates <code>with_custodian_and_ward</code> and |
| <code>with_custodian_and_ward_postcall</code> differ in the point at |
| which they take effect. |
| <p> |
| In order to reduce the chance of inadvertently creating dangling |
| pointers, the default is to do lifetime binding <i>before</i> the |
| underlying C++ object is invoked. However, before invocation the result |
| object is not available, so |
| <code>with_custodian_and_ward_postcall</code> is provided to bind |
| lifetimes after invocation. Also, if a C++ exception is thrown after |
| <code>with_custodian_and_ward<>::precall</code> but before the |
| underlying C++ object actually stores a pointer, the lifetime of the |
| custodian and ward objects will be artificially bound together, so one |
| might choose <code>with_custodian_and_ward_postcall</code> instead, |
| depending on the semantics of the function being wrapped. |
| </p> |
| <p> |
| Please note that this is <i>not</i> the appropriate tool to use when |
| wrapping functions which <b>transfer ownership</b> of a raw pointer |
| across the function-call boundary. Please see the <a href= |
| "faq.html#ownership">FAQ</a> if you want to do that. |
| </p> |
| <h2> |
| <a name="classes"></a>Classes |
| </h2> |
| <h3> |
| <a name="with_custodian_and_ward-spec"></a>Class template |
| <code>with_custodian_and_ward</code> |
| </h3> |
| <table border="1" summary="with_custodian_and_ward template parameters"> |
| <caption> |
| <b><code>with_custodian_and_ward</code> template parameters</b> |
| </caption> |
| <tr> |
| <th> |
| Parameter |
| </th> |
| <th> |
| Requirements |
| </th> |
| <th> |
| Description |
| </th> |
| <th> |
| Default |
| </th> |
| </tr> |
| <tr> |
| <td> |
| <code>custodian</code> |
| </td> |
| <td> |
| A positive compile-time constant of type <code>std::size_t</code>. |
| </td> |
| <td> |
| The 1-based index of the parameter which is the dependency in the |
| lifetime relationship to be established. If used to wrap a member |
| function, parameter 1 is the target object (<code>*this</code>). |
| Note that if the target Python object type doesn't support weak |
| references, a Python <code>TypeError</code> exception will be |
| raised when the C++ object being wrapped is called. |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <code>ward</code> |
| </td> |
| <td> |
| A positive compile-time constant of type <code>std::size_t</code>. |
| </td> |
| <td> |
| The 1-based index of the parameter which is the dependent in the |
| lifetime relationship to be established. If used to wrap a member |
| function, parameter 1 is the target object (<code>*this</code>). |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <code>Base</code> |
| </td> |
| <td> |
| A model of <a href="CallPolicies.html">CallPolicies</a> |
| </td> |
| <td> |
| Used for <a href="CallPolicies.html#composition">policy |
| composition</a>. |
| </td> |
| <td> |
| <code><a href= |
| "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code> |
| </td> |
| </tr> |
| </table> |
| <h4> |
| <a name="with_custodian_and_ward-spec-synopsis"></a>Class template |
| <code>with_custodian_and_ward</code> synopsis |
| </h4> |
| <pre> |
| namespace boost { namespace python |
| { |
| template <std::size_t custodian, std::size_t ward, class Base = default_call_policies> |
| struct with_custodian_and_ward : Base |
| { |
| static bool precall(PyObject* args); |
| }; |
| }} |
| </pre> |
| <h4> |
| <a name="with_custodian_and_ward-spec-statics"></a>Class |
| <code>with_custodian_and_ward</code> static functions |
| </h4> |
| <pre> |
| bool precall(PyObject* args); |
| </pre> |
| <dl class="function-semantics"> |
| <dt> |
| <b>Requires:</b> <code><a href= |
| "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) |
| != 0</code> |
| </dt> |
| <dt> |
| <b>Effects:</b> Makes the lifetime of the argument indicated by |
| <code>ward</code> dependent on the lifetime of the argument indicated |
| by <code>custodian</code>. |
| </dt> |
| <dt> |
| <b>Returns:</b> <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. |
| </dt> |
| </dl><!-- xxxxxx --> |
| <h3> |
| <a name="with_custodian_and_ward_postcall-spec"></a>Class template |
| <code>with_custodian_and_ward_postcall</code> |
| </h3> |
| <table border="1" summary= |
| "with_custodian_and_ward_postcall template parameters"> |
| <caption> |
| <b><code>with_custodian_and_ward_postcall</code> template |
| parameters</b> |
| </caption> |
| <tr> |
| <th> |
| Parameter |
| </th> |
| <th> |
| Requirements |
| </th> |
| <th> |
| Description |
| </th> |
| <th> |
| Default |
| </th> |
| </tr> |
| <tr> |
| <td> |
| <code>custodian</code> |
| </td> |
| <td> |
| A compile-time constant of type <code>std::size_t</code>. |
| </td> |
| <td> |
| The index of the parameter which is the dependency in the lifetime |
| relationship to be established. Zero indicates the result object; 1 |
| indicates the first argument. If used to wrap a member function, |
| parameter 1 is the target object (<code>*this</code>). Note that if |
| the target Python object type doesn't support weak references, a |
| Python <code>TypeError</code> exception will be raised when the C++ |
| object being wrapped is called. |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <code>ward</code> |
| </td> |
| <td> |
| A compile-time constant of type <code>std::size_t</code>. |
| </td> |
| <td> |
| The index of the parameter which is the dependent in the lifetime |
| relationship to be established. Zero indicates the result object; 1 |
| indicates the first argument. If used to wrap a member function, |
| parameter 1 is the target object (<code>*this</code>). |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <code>Base</code> |
| </td> |
| <td> |
| A model of <a href="CallPolicies.html">CallPolicies</a> |
| </td> |
| <td> |
| Used for <a href="CallPolicies.html#composition">policy |
| composition</a>. |
| </td> |
| <td> |
| <code><a href= |
| "default_call_policies.html#default_call_policies-spec">default_call_policies</a></code> |
| </td> |
| </tr> |
| </table> |
| <h4> |
| <a name="with_custodian_and_ward_postcall-spec-synopsis"></a>Class |
| template <code>with_custodian_and_ward_postcall</code> synopsis |
| </h4> |
| <pre> |
| namespace boost { namespace python |
| { |
| template <std::size_t custodian, std::size_t ward, class Base = default_call_policies> |
| struct with_custodian_and_ward_postcall : Base |
| { |
| static PyObject* postcall(PyObject* args, PyObject* result); |
| }; |
| }} |
| </pre> |
| <h4> |
| <a name="with_custodian_and_ward_postcall-spec-statics"></a>Class |
| <code>with_custodian_and_ward_postcall</code> static functions |
| </h4> |
| <pre> |
| PyObject* postcall(PyObject* args, PyObject* result); |
| </pre> |
| <dl class="function-semantics"> |
| <dt> |
| <b>Requires:</b> <code><a href= |
| "http://www.python.org/doc/2.2/api/tupleObjects.html#l2h-476">PyTuple_Check</a>(args) |
| != 0</code>, <code>result != 0</code>. |
| </dt> |
| <dt> |
| <b>Effects:</b> Makes the lifetime of the object indicated by |
| <code>ward</code> dependent on the lifetime of the object indicated |
| by <code>custodian</code>. |
| </dt> |
| <dt> |
| <b>Returns:</b> <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, <code>true</code> otherwise. |
| </dt> |
| </dl> |
| <h2> |
| <a name="examples"></a>Example |
| </h2>The following example shows how |
| <code>with_custodian_and_ward_postcall</code> is used by the library to |
| implement <code><a href= |
| "return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a></code> |
| |
| <pre> |
| template <std::size_t owner_arg = 1, class Base = default_call_policies> |
| struct return_internal_reference |
| : with_custodian_and_ward_postcall<0, owner_arg, Base> |
| { |
| typedef <a href= |
| "reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a> result_converter; |
| }; |
| </pre> |
| <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> |
| </body> |
| </html> |