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