boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-24 18:12:43 +00:00
Code Issues Projects Releases Wiki Activity

initial commit

Browse Source 
[SVN r13979]
This commit is contained in:
Dave Abrahams
2002-05-19 20:23:00 +00:00
parent beb6cca88d
commit dde6c42421
1 changed files with 278 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
doc/v2/with_custodian_and_ward.html Normal file
View File

@@ -0,0 +1,278 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<meta name="generator" content="HTML Tidy, 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 - &lt;boost/python/with_custodian_and_ward.hpp&gt;</title>
<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="../../../../c++boost.gif" border="0"></a></h3>
<td valign="top">
<h1 align="center">Boost.Python</h1>
<h2 align="center">Header &lt;boost/python/with_custodian_and_ward.hpp&gt;</h2>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a>
<dt><a href="#classes">Classes</a>
<dd>
<dl class="page-index">
<dt><a href="#with_custodian_and_ward-spec">Class Template <code>with_custodian_and_ward</code></a>
<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><a href="#with_custodian_and_ward-spec-statics">Class
<code>with_custodian_and_ward</code> static functions</a>
</dl>
</dl>
<dt><a href="#examples">Example</a>
</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). 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&lt;&gt;::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.
<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>Requirements
<th>Description
<th>Default
<tr>
<td><code>custodian</code>
<td>A positive compile-time constant of type
<code>std::size_t</code>.
<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.
<tr>
<td><code>ward</code>
<td>A positive compile-time constant of type
<code>std::size_t</code>.
<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>).
<tr>
<td><code>Base</code>
<td>A model of <a href="CallPolicies.html">CallPolicies</a>
<td>Used for <a href="CallPolicies.html#composition">policy composition</a>.
<td><code><a href="default_call_policies.html#default_call_policies-spec">default_call_policies</a></code>
</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 &lt;std::size_t custodian, std::size_t ward, class Base = default_call_policies&gt;
struct with_custodian_and_ward : Base
{
static bool precall(PyObject* args);
};
}}
</pre>
<h4><a name="default_call_policies-spec-statics"></a>Class
<code>default_call_policies</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><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><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>()&nbsp;!=&nbsp;0</code>
upon failure, <code>true</code> otherwise.
</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>Requirements
<th>Description
<th>Default
<tr>
<td><code>custodian</code>
<td>A compile-time constant of type
<code>std::size_t</code>.
<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.
<tr>
<td><code>ward</code>
<td>A compile-time constant of type <code>std::size_t</code>.
<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>).
<tr>
<td><code>Base</code>
<td>A model of <a href="CallPolicies.html">CallPolicies</a>
<td>Used for <a href="CallPolicies.html#composition">policy
composition</a>.
<td><code><a href="default_call_policies.html#default_call_policies-spec">default_call_policies</a></code>
</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 &lt;std::size_t custodian, std::size_t ward, class Base = default_call_policies&gt;
struct with_custodian_and_ward_postcall : Base
{
static PyObject* postcall(PyObject* args, PyObject* result);
};
}}
</pre>
<h4><a name="default_call_policies-spec-statics"></a>Class
<code>default_call_policies</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&nbsp;!=&nbsp;0</code>.
<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><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>()&nbsp;!=&nbsp;0</code>
upon failure, <code>true</code> otherwise.
</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 -->
19 February, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
<p><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
Abrahams</a> 2002. All Rights Reserved.</i>