boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-20 16:52:15 +00:00
Code Issues Projects Releases Wiki Activity

initial commit

Browse Source 
[SVN r13755]
This commit is contained in:
Dave Abrahams
2002-05-08 19:07:22 +00:00
parent c9097566e2
commit 7cd32fc4eb
1 changed files with 217 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

217
doc/v2/has_back_reference.html Normal file
View File

@@ -0,0 +1,217 @@
<!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/has_back_reference.hpp&gt;</title>
<style type="text/css">
p.c3 {font-style: italic}
h2.c2 {text-align: center}
h1.c1 {text-align: center}
</style>
<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 class="c1">Boost.Python</h1>
<h2 class="c2">Header
&lt;boost/python/has_back_reference.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="#has_back_reference-spec">Class template
<code>has_back_reference</code></a>
<dd>
<dl class="page-index">
<dt><a href=
"#has_back_reference-spec-synopsis">Class template
<code>has_back_reference</code> synopsis</a>
</dl>
<dt><a href="#examples">Example(s)</a>
</dl>
</dl>
<hr>
<h2><a name="introduction"></a>Introduction</h2>
<p><code>&lt;boost/python/has_back_reference.hpp&gt;</code>
defines the traits class template
<code>has_back_reference&lt;&gt;</code>, which can be
specialized by the user to indicate that a wrapped class
instance holds a <code>PyObject*</code> corresponding to a
Python object.
<h2><a name="classes"></a>Classes</h2>
<h3><a name="has_back_reference-spec"></a>Class template
<code>has_back_reference</code></h3>
<p>A unary metafunction whose <code>value</code> is true iff
its argument is a <code>pointer_wrapper&lt;&gt;</code>.
<h4><a name="has_back_reference-spec-synopsis"></a>Class
template <code>has_back_reference</code> synopsis</h4>
<pre>
namespace boost { namespace python
{
template&lt;class WrappedClass&gt; class has_back_reference
{
static <i>unspecified</i> value = false;
};
}}
</pre>
<p>A &quot;<a href=
"../../../../more/generic_programming.html#traits">traits
class</a>&quot; which is inspected by Boost.Python to
determine how wrapped classes can be constructed.
<dl class="traits-semantics">
<dt><code>value</code> is an integral constant convertible
to bool of unspecified type.
<dt>Specializations may substitute a value convertible to
<code>true</code> for <code>value</code> iff for each invocation of
<code>class_&lt;WrappedClass&gt;::def_init(args&lt;</code><i>type-sequence...</i><code>&gt;())</code>,
there exists a corresponding constructor
<code>WrappedClass::WrappedClass(PyObject*,&nbsp;</code><i>type-sequence...</i><code>)</code>. If
such a specialization exists, the <code>WrappedClass</code>
constructors will be called with a &quot;back reference&quot; pointer
to the corresponding Python object whenever they are invoked from
Python.
</dl>
<h2><a name="examples"></a>Example</h2>
<h3>C++ module definition</h3>
<pre>
#include &lt;boost/python/class.hpp&gt;
#include &lt;boost/python/module.hpp&gt;
#include &lt;boost/python/has_back_reference.hpp&gt;
#include &lt;boost/shared_ptr.hpp&gt;
using namespace boost::python;
struct X
{
X(PyObject* self) : m_self(self), m_x(0) {}
X(PyObject* self, int x) : m_self(self), m_x(x) {}
PyObject* self() { return m_self; }
int get() { return m_x; }
void set(int x) { m_x = x; }
PyObject* m_self;
int x;
};
// specialize has_back_reference for X
namespace boost { namespace python
{
template &lt;&gt;
struct has_back_reference&lt;X&gt;
{
enum { value = true; }
}
}}
struct Y
{
Y() : m_x(0) {}
Y(int x) : m_x(x) {}
int get() { return m_x; }
void set(int x) { m_x = x; }
int x;
};
boost::shared_ptr&lt;Y&gt; Y_self(boost::shared_ptr&lt;Y&gt; self) const { return self; }
BOOST_PYTHON_MODULE_INIT(back_references)
{
module(&quot;back_references&quot;)
.add(
class_&lt;X&gt;(&quot;X&quot;)
.def_init()
.def_init(args&lt;int&gt;())
.def(&quot;self&quot;, &amp;X::self)
.def(&quot;get&quot;, &amp;X::get)
.def(&quot;set&quot;, &amp;X::set)
)
.add(
class_&lt;Y, shared_ptr&lt;Y&gt; &gt;(&quot;Y&quot;)
.def_init()
.def_init(args&lt;int&gt;())
.def(&quot;get&quot;, &amp;Y::get)
.def(&quot;set&quot;, &amp;Y::set)
.def(&quot;self&quot;, Y_self)
)
;
}
</pre>
The following Python session illustrates that <code>x.self()</code>
returns the same Python object on which it is invoked, while
<code>y.self()</code> must create a new Python object which refers to
the same Y instance.
<h3>Python code</h3>
<pre>
&gt;&gt;&gt; from back_references import *
&gt;&gt;&gt; x = X(1)
&gt;&gt;&gt; x2 = x.self()
&gt;&gt;&gt; x2 is x
<b>1</b>
&gt;&gt;&gt; (x.get(), x2.get())
(1, 1)
&gt;&gt;&gt; x.set(10)
&gt;&gt;&gt; (x.get(), x2.get())
(10, 10)
&gt;&gt;&gt;
&gt;&gt;&gt;
&gt;&gt;&gt; y = Y(2)
&gt;&gt;&gt; y2 = y.self()
&gt;&gt;&gt; y2 is y
<b>0</b>
&gt;&gt;&gt; (y.get(), y2.get())
(2, 2)
&gt;&gt;&gt; y.set(20)
&gt;&gt;&gt; (y.get(), y2.get())
(20, 20)
</pre>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
07 May, 2002
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
<p class="c3">&copy; Copyright <a href=
"../../../../people/dave_abrahams.htm">Dave Abrahams</a>
2002. All Rights Reserved.