| <!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 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 - <boost/python/has_back_reference.hpp></title> |
| |
| <style type="text/css"> |
| p.c3 {font-style: italic} |
| h2.c2 {text-align: center} |
| h1.c1 {text-align: center} |
| </style> |
| </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 class="c1"><a href="../index.html">Boost.Python</a></h1> |
| |
| <h2 class="c2">Header |
| <boost/python/has_back_reference.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="#has_back_reference-spec">Class template |
| <code>has_back_reference</code></a></dt> |
| |
| <dd> |
| <dl class="page-index"> |
| <dt><a href="#has_back_reference-spec-synopsis">Class template |
| <code>has_back_reference</code> synopsis</a></dt> |
| </dl> |
| </dd> |
| |
| <dt><a href="#examples">Example(s)</a></dt> |
| </dl> |
| </dd> |
| </dl> |
| <hr> |
| |
| <h2><a name="introduction"></a>Introduction</h2> |
| |
| <p><code><boost/python/has_back_reference.hpp></code> defines the |
| predicate metafunction <code>has_back_reference<></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.</p> |
| |
| <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<></code>.</p> |
| |
| <h4><a name="has_back_reference-spec-synopsis"></a>Class template |
| <code>has_back_reference</code> synopsis</h4> |
| <pre> |
| namespace boost { namespace python |
| { |
| template<class WrappedClass> class has_back_reference |
| { |
| typedef mpl::false_ type; |
| }; |
| }} |
| </pre> |
| <p>A "<a href="../../../mpl/doc/refmanual/metafunction.html"> |
| metafunction</a>" that is inspected by Boost.Python to determine how |
| wrapped classes can be constructed.</p> |
| |
| <dl class="traits-semantics"> |
| <dt><code>type::value</code> is an integral constant convertible to bool |
| of unspecified type.</dt> |
| |
| <dt>Specializations may substitute a <code>true</code>-valued integral constant wrapper for |
| <code>type</code> iff for each invocation of |
| <code>class_<WrappedClass>::def(init<</code> |
| <i>type-sequence...</i><code>>())</code> and the implicitly wrapped |
| copy constructor (unless it is <a href="class.html#class_-spec"> |
| noncopyable</a>), there exists a corresponding constructor |
| <code>WrappedClass::WrappedClass(PyObject*, </code> |
| <i>type-sequence...</i><code>)</code>. If such a specialization exists, |
| the <code>WrappedClass</code> constructors will be called with a "back |
| reference" pointer to the corresponding Python object whenever they are |
| invoked from Python. The easiest way to provide this nested <code> |
| type |
| </code> |
| is to |
| derive the specialization from <code>mpl::true_</code>. |
| </dt> |
| </dl> |
| |
| <h2><a name="examples"></a>Example</h2> |
| |
| <h3>C++ module definition</h3> |
| <pre> |
| #include <boost/python/class.hpp> |
| #include <boost/python/module.hpp> |
| #include <boost/python/has_back_reference.hpp> |
| #include <boost/python/handle.hpp> |
| #include <boost/shared_ptr.hpp> |
| |
| using namespace boost::python; |
| using boost::shared_ptr; |
| |
| struct X |
| { |
| X(PyObject* self) : m_self(self), m_x(0) {} |
| X(PyObject* self, int x) : m_self(self), m_x(x) {} |
| X(PyObject* self, X const& other) : m_self(self), m_x(other.m_x) {} |
| |
| handle<> self() { return handle<>(borrowed(m_self)); } |
| int get() { return m_x; } |
| void set(int x) { m_x = x; } |
| |
| PyObject* m_self; |
| int m_x; |
| }; |
| |
| // specialize has_back_reference for X |
| namespace boost { namespace python |
| { |
| template <> |
| struct has_back_reference<X> |
| : mpl::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 m_x; |
| }; |
| |
| shared_ptr<Y> |
| Y_self(shared_ptr<Y> self) { return self; } |
| |
| BOOST_PYTHON_MODULE(back_references) |
| { |
| class_<X>("X") |
| .def(init<int>()) |
| .def("self", &X::self) |
| .def("get", &X::get) |
| .def("set", &X::set) |
| ; |
| |
| class_<Y, shared_ptr<Y> >("Y") |
| .def(init<int>()) |
| .def("get", &Y::get) |
| .def("set", &Y::set) |
| .def("self", 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> |
| >>> from back_references import * |
| >>> x = X(1) |
| >>> x2 = x.self() |
| >>> x2 is x |
| <b>1</b> |
| >>> (x.get(), x2.get()) |
| (1, 1) |
| >>> x.set(10) |
| >>> (x.get(), x2.get()) |
| (10, 10) |
| >>> |
| >>> |
| >>> y = Y(2) |
| >>> y2 = y.self() |
| >>> y2 is y |
| <b>0</b> |
| >>> (y.get(), y2.get()) |
| (2, 2) |
| >>> y.set(20) |
| >>> (y.get(), y2.get()) |
| (20, 20) |
| </pre> |
| |
| <p>Revised |
| <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
| 18 July, 2004 |
| <!--webbot bot="Timestamp" endspan i-checksum="39359" --> |
| </p> |
| |
| <p class="c3">© Copyright <a href= |
| "http://www.boost.org/people/dave_abrahams.htm">Dave Abrahams</a> 2002 |
| .</p> |
| </body> |
| </html> |
| |