boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-23 05:42:30 +00:00
Code Issues Projects Releases Wiki Activity

doc update

Browse Source 
[SVN r15561]
This commit is contained in:
Dave Abrahams
2002-09-29 20:30:17 +00:00
parent 6b5ea675c3
commit 170bbea166
3 changed files with 825 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1000
doc/v2/operators.html
View File

File diff suppressed because it is too large Load Diff

83
doc/v2/reference_existing_object.html
View File

@@ -1,47 +1,59 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<meta name="generator" content="HTML Tidy, see www.w3.org">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 1st August 2002), 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/reference_existing_object.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">Boost.Python</h1>
<h2 align="center">Header
&lt;boost/python/reference_existing_object.hpp&gt;</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#classes">Classes</a>
<dt><a href="#classes">Classes</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#reference_existing_object-spec">Class
<code>reference_existing_object</code></a>
<code>reference_existing_object</code></a></dt>
<dd>
<dl class="page-index">
<dt><a href="#reference_existing_object-spec-synopsis">Class
<code>reference_existing_object</code> synopsis</a>
<code>reference_existing_object</code> synopsis</a></dt>
<dt><a href="#reference_existing_object-spec-metafunctions">Class
<code>reference_existing_object</code> metafunctions</a>
<dt><a href=
"#reference_existing_object-spec-metafunctions">Class
<code>reference_existing_object</code> metafunctions</a></dt>
</dl>
</dd>
</dl>
</dd>
<dt><a href="#examples">Example</a>
<dt><a href="#examples">Example</a></dt>
</dl>
<hr>
@@ -51,19 +63,20 @@
<code>reference_existing_object</code></h3>
<p><code>reference_existing_object</code> is a model of <a href=
"ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a> which can be
used to wrap C++ functions which return a reference or pointer to a C++
object. When the wrapped function is called, the value referenced by its
return value is not copied. A new Python object is created which contains a
pointer to the referent, and no attempt is made to ensure that the lifetime
of the referent is at least as long as that of the corresponding Python
object. Thus, it can be <font color="#ff0000"><b>highly
dangerous</b></font> to use <code>reference_existing_object</code> without
additional lifetime management from such models of <a href=
"ResultConverter.html#ResultConverterGenerator-concept">ResultConverterGenerator</a>
which can be used to wrap C++ functions which return a reference or
pointer to a C++ object. When the wrapped function is called, the value
referenced by its return value is not copied. A new Python object is
created which contains a pointer to the referent, and no attempt is made
to ensure that the lifetime of the referent is at least as long as that
of the corresponding Python object. Thus, it can be <font color=
"#ff0000"><b>highly dangerous</b></font> to use
<code>reference_existing_object</code> without additional lifetime
management from such models of <a href=
"CallPolicies.html">CallPolicies</a> as <a href=
"with_custodian_and_ward.html#with_custodian_and_ward-spec">with_custodian_and_ward</a>.
This class is used in the implementation of <a href=
"return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a>.
"return_internal_reference.html#return_internal_reference-spec">return_internal_reference</a>.</p>
<h4><a name="reference_existing_object-spec-synopsis"></a>Class
<code>reference_existing_object</code> synopsis</h4>
@@ -85,22 +98,22 @@ template &lt;class T&gt; struct apply
<dl class="metafunction-semantics">
<dt><b>Requires:</b> <code>T</code> is <code>U&amp;</code> or
<code>U*</code>for some <code>U</code>.
<code>U*</code>for some <code>U</code>.</dt>
<dt><b>Returns:</b> <code>typedef <a href=
"to_python_indirect.html#to_python_indirect-spec">to_python_indirect</a>&lt;T,V&gt;
type</code>, where <code>V</code> is a <a href=
"to_python_indirect.html#HolderObjectGenerator">HolderObjectGenerator</a>
which constructs an instance holder containing an <i>unowned</i>
<code>U*</code> pointing to the referent of the wrapped function's return
value.
<code>U*</code> pointing to the referent of the wrapped function's
return value.</dt>
</dl>
<h2><a name="examples"></a>Example</h2>
<p>In C++:
<p>In C++:</p>
<pre>
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/python/reference_existing_object.hpp&gt;
#include &lt;boost/python/return_value_policy.hpp&gt;
@@ -130,12 +143,10 @@ Singleton&amp; get_it()
using namespace boost::python;
BOOST_PYTHON_MODULE_INIT(singleton)
{
module("singleton")
.def("get_it", get_it)
.add(
class_&lt;Singleton&gt;()
.def("exchange", &amp;Singleton::exchange)
);
def("get_it", get_it, reference_existing_object());
class_&lt;Singleton&gt;()
.def("exchange", &amp;Singleton::exchange)
;
}
</pre>
In Python:
@@ -153,9 +164,13 @@ BOOST_PYTHON_MODULE_INIT(singleton)
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
14 February 2002 <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
29 September 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><i>&copy; Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
Reserved.</i></p>
</body>
</html>

178
doc/v2/return_internal_reference.html
View File

@@ -1,114 +1,129 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<meta name="generator" content="HTML Tidy, see www.w3.org">
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 1st August 2002), 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/return_internal_reference.hpp&gt;</title>
<title>Boost.Python -
&lt;boost/python/return_internal_reference.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">Boost.Python</h1>
<h2 align="center">Header &lt;boost/python/return_internal_reference.hpp&gt;</h2>
<h2 align="center">Header
&lt;boost/python/return_internal_reference.hpp&gt;</h2>
</td>
</tr>
</table>
<hr>
<h2>Contents</h2>
<dl class="page-index">
<dt><a href="#introduction">Introduction</a>
<dt><a href="#introduction">Introduction</a></dt>
<dt><a href="#classes">Classes</a>
<dt><a href="#classes">Classes</a></dt>
<dd>
<dl class="page-index">
<dt><a href="#return_internal_reference-spec">Class Template <code>return_internal_reference</code></a>
<dt><a href="#return_internal_reference-spec">Class Template
<code>return_internal_reference</code></a></dt>
<dd>
<dl class="page-index">
<dt><a href="#return_internal_reference-spec-synopsis">Class Template
<code>return_internal_reference</code> synopsis</a>
<dt><a href="#return_internal_reference-spec-synopsis">Class
Template <code>return_internal_reference</code>
synopsis</a></dt>
<dt><a href="#return_internal_reference-spec-statics">Class
<code>return_internal_reference</code> static functions</a>
<code>return_internal_reference</code> static
functions</a></dt>
</dl>
</dd>
</dl>
</dd>
<dt><a href="#examples">Example</a>
<dt><a href="#examples">Example</a></dt>
</dl>
<hr>
<h2><a name="introduction"></a>Introduction</h2>
<code>return_internal_reference</code> instantiations are models of <a href=
"CallPolicies.html">CallPolicies</a> which allow pointers and
<code>return_internal_reference</code> instantiations are models of <a
href="CallPolicies.html">CallPolicies</a> which allow pointers and
references to objects held internally by a free or member function
argument or from the target of a member function to be returned
safely without making a copy of the referent. The default for its
first template argument handles the common case where the
containing object is the target (<code>*this</code>) of a wrapped
member function.
argument or from the target of a member function to be returned safely
without making a copy of the referent. The default for its first template
argument handles the common case where the containing object is the
target (<code>*this</code>) of a wrapped member function.
<h2><a name="classes"></a>Classes</h2>
<h3><a name="return_internal_reference-spec"></a>Class template <code>return_internal_reference</code></h3>
<h3><a name="return_internal_reference-spec"></a>Class template
<code>return_internal_reference</code></h3>
<table border="1" summary="return_internal_reference template parameters">
<table border="1" summary=
"return_internal_reference template parameters">
<caption>
<b><code>return_internal_reference</code> template parameters</b>
</caption>
<tr>
<th>Parameter
<th>Requirements
<th>Description
<th>Default
<tr>
<td><code>owner_arg</code>
<th>Parameter</th>
<th>Requirements</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><code>owner_arg</code></td>
<td>A positive compile-time constant of type
<code>std::size_t</code>.
<code>std::size_t</code>.</td>
<td>The index of the parameter which contains the object to
which the reference or pointer is being returned. 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
function being wrapped is called.
<td>The index of the parameter which contains the object to which the
reference or pointer is being returned. 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 function being wrapped is called.</td>
<td>1
<td>1</td>
</tr>
<tr>
<td><code>Base</code>
<td><code>Base</code></td>
<td>A model of <a href="CallPolicies.html">CallPolicies</a>
<td>A model of <a href="CallPolicies.html">CallPolicies</a></td>
<td>Used for policy composition. Any
<code>result_converter</code> it supplies will be overridden by
<code>return_internal_reference</code>, but its
<code>precall</code> and <code>postcall</code> policies are
composed as described here <a
href="CallPolicies.html#composition">CallPolicies</a>.
<td><code><a href="default_call_policies.html#default_call_policies-spec">default_call_policies</a></code>
<td>Used for policy composition. Any <code>result_converter</code> it
supplies will be overridden by
<code>return_internal_reference</code>, but its <code>precall</code>
and <code>postcall</code> policies are composed as described here <a
href="CallPolicies.html#composition">CallPolicies</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="return_internal_reference-spec-synopsis"></a>Class template <code>return_internal_reference</code> synopsis</h4>
<h4><a name="return_internal_reference-spec-synopsis"></a>Class template
<code>return_internal_reference</code> synopsis</h4>
<pre>
namespace boost { namespace python
{
@@ -116,31 +131,34 @@ namespace boost { namespace python
struct return_internal_reference : Base
{
static PyObject* postcall(PyObject*, PyObject* result);
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>
<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>
<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>Returns:</b> <code><a href="with_custodian_and_ward.html#with_custodian_and_ward_postcall-spec-statics">with_custodian_and_ward_postcall::postcall(args, result)</a></code>
<dt><b>Returns:</b> <code><a href=
"with_custodian_and_ward.html#with_custodian_and_ward_postcall-spec-statics">
with_custodian_and_ward_postcall::postcall(args,
result)</a></code></dt>
</dl>
<h2><a name="examples"></a>Example</h2>
<h3>C++ module definition</h3>
<h3>C++ module definition</h3>
<pre>
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/module_init.hpp&gt;
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/python/return_internal_reference.hpp&gt;
@@ -168,24 +186,20 @@ class Foo
using namespace boost::python;
BOOST_PYTHON_MODULE_INIT(internal_refs)
{
module m(&quot;internal_refs&quot;)
.add(
class_&lt;Bar&gt;()
.def(&quot;get_x&quot;, &amp;Bar::get_x)
.def(&quot;set_x&quot;, &amp;Bar::set_x)
)
.add(
class_&lt;Foo&gt;()
.def_init(args&lt;int&gt;())
.def(&quot;get_bar&quot;, &amp;Foo::get_bar
, return_internal_reference&lt;&gt;())
)
class_&lt;Bar&gt;()
.def("get_x", &amp;Bar::get_x)
.def("set_x", &amp;Bar::set_x)
;
class_&lt;Foo&gt;()
.def_init(args&lt;int&gt;())
.def("get_bar", &amp;Foo::get_bar
, return_internal_reference&lt;&gt;())
;
}
</pre>
<h3>Python code</h3>
<h3>Python code</h3>
<pre>
&gt;&gt;&gt; from internal_refs import *
&gt;&gt;&gt; f = Foo(3)
@@ -202,9 +216,13 @@ BOOST_PYTHON_MODULE_INIT(internal_refs)
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
15 February, 2002
15 February, 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><i>&copy; Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a> 2002. All Rights
Reserved.</i></p>
</body>
</html>