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

Add FAQ reference

Browse Source 
[SVN r17249]
This commit is contained in:
Dave Abrahams
2003-02-06 13:50:31 +00:00
parent 5bcf90766f
commit ac55c5ccf7
1 changed files with 299 additions and 223 deletions
Download Patch File Download Diff File Expand all files Collapse all files

522
doc/v2/with_custodian_and_ward.html
View File

@@ -1,149 +1,199 @@
<!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">
<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 - &lt;boost/python/with_custodian_and_ward.hpp&gt;</title>
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
"header">
<title>
Boost.Python - &lt;boost/python/with_custodian_and_ward.hpp&gt;
</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="../../../../c++boost.gif" border="0"></a></h3>
<h3>
<a href="../../../../index.htm"><img height="86" width="277"
alt="C++ Boost" src="../../../../c++boost.gif" border="0">
</a>
</h3>
</td>
<td valign="top">
<h1 align="center"><a href="../index.html">Boost.Python</a></h1>
<h2 align="center">Header &lt;boost/python/with_custodian_and_ward.hpp&gt;</h2>
<h1 align="center">
<a href="../index.html">Boost.Python</a>
</h1>
<h2 align="center">
Header &lt;boost/python/with_custodian_and_ward.hpp&gt;
</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<h2>
Contents
</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a>
<dt><a href="#classes">Classes</a>
<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>
<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><a href="#with_custodian_and_ward-spec-statics">Class
<code>with_custodian_and_ward</code> static functions</a>
<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>
<dt><a href="#with_custodian_and_ward_postcall-spec">Class Template <code>with_custodian_and_ward_postcall</code></a>
</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><a href="#with_custodian_and_ward_postcall-spec-statics">Class
<code>with_custodian_and_ward_postcall</code> static functions</a>
<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>
<dt><a href="#examples">Example</a>
</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
<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&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>
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&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.
</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>Requirements
<th>Description
<th>Default
<th>
Parameter
</th>
<th>
Requirements
</th>
<th>
Description
</th>
<th>
Default
</th>
</tr>
<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.
<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>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>).
<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>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>
<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>
<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;
@@ -153,85 +203,107 @@ namespace boost { namespace python
};
}}
</pre>
<h4><a name="with_custodian_and_ward-spec-statics"></a>Class
<code>with_custodian_and_ward</code> static functions</h4>
<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><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">
<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>()&nbsp;!=&nbsp;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>
<b><code>with_custodian_and_ward_postcall</code> template
parameters</b>
</caption>
<tr>
<th>Parameter
<th>Requirements
<th>Description
<th>Default
<th>
Parameter
</th>
<th>
Requirements
</th>
<th>
Description
</th>
<th>
Default
</th>
</tr>
<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.
<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>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>).
<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>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>
<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>
<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;
@@ -241,51 +313,55 @@ namespace boost { namespace python
};
}}
</pre>
<h4><a name="with_custodian_and_ward_postcall-spec-statics"></a>Class
<code>with_custodian_and_ward_postcall</code> static functions</h4>
<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&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.
<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>
<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>()&nbsp;!=&nbsp;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>
<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 &lt;std::size_t owner_arg = 1, class Base = default_call_policies&gt;
struct return_internal_reference
: with_custodian_and_ward_postcall&lt;0, owner_arg, Base&gt;
{
typedef <a href="reference_existing_object.html#reference_existing_object-spec">reference_existing_object</a> result_converter;
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><i>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
Abrahams</a> 2002. All Rights Reserved.</i>
<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>&copy; Copyright <a href="../../../../people/dave_abrahams.htm">Dave
Abrahams</a> 2002. All Rights Reserved.</i>
</p>
</body>
</html>