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