• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[section boost/python/has_back_reference.hpp]
2[section Introduction]
3<boost/python/has_back_reference.hpp> defines the predicate metafunction `has_back_reference<>`, which can be specialized by the user to indicate that a wrapped class instance holds a `PyObject*` corresponding to a Python object.
4[endsect]
5[section Class template `has_back_reference`]
6A unary metafunction whose value is true iff its argument is a `pointer_wrapper<>`.
7``
8namespace boost { namespace python
9{
10    template<class WrappedClass> class has_back_reference
11    {
12        typedef mpl::false_ type;
13    };
14}}
15``
16
17A metafunction that is inspected by Boost.Python to determine how wrapped classes can be constructed.
18
19`type::value` is an integral constant convertible to bool of unspecified type.
20Specializations may substitute a true-valued integral constant wrapper for type iff for each invocation of `class_<WrappedClass>::def(init< type-sequence...>())` and the implicitly wrapped copy constructor (unless it is noncopyable), there exists a corresponding constructor `WrappedClass::WrappedClass(PyObject*,  type-sequence...)`. If such a specialization exists, the WrappedClass 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 type is to derive the specialization from `mpl::true_`.
21
22[endsect]
23[section Examples]
24In C++:
25``
26#include <boost/python/class.hpp>
27#include <boost/python/module.hpp>
28#include <boost/python/has_back_reference.hpp>
29#include <boost/python/handle.hpp>
30#include <boost/shared_ptr.hpp>
31
32using namespace boost::python;
33using boost::shared_ptr;
34
35struct X
36{
37    X(PyObject* self) : m_self(self), m_x(0) {}
38    X(PyObject* self, int x) : m_self(self), m_x(x) {}
39    X(PyObject* self, X const& other) : m_self(self), m_x(other.m_x) {}
40
41    handle<> self() { return handle<>(borrowed(m_self)); }
42    int get() { return m_x; }
43    void set(int x) { m_x = x; }
44
45    PyObject* m_self;
46    int m_x;
47};
48
49// specialize has_back_reference for X
50namespace boost { namespace python
51{
52  template <>
53  struct has_back_reference<X>
54    : mpl::true_
55  {};
56}}
57
58struct Y
59{
60    Y() : m_x(0) {}
61    Y(int x) : m_x(x) {}
62    int get() { return m_x; }
63    void set(int x) { m_x = x; }
64
65    int m_x;
66};
67
68shared_ptr<Y>
69Y_self(shared_ptr<Y> self) { return self; }
70
71BOOST_PYTHON_MODULE(back_references)
72{
73    class_<X>("X")
74       .def(init<int>())
75       .def("self", &X::self)
76       .def("get", &X::get)
77       .def("set", &X::set)
78       ;
79
80    class_<Y, shared_ptr<Y> >("Y")
81       .def(init<int>())
82       .def("get", &Y::get)
83       .def("set", &Y::set)
84       .def("self", Y_self)
85       ;
86}
87``
88 The following Python session illustrates that x.self() returns the same Python object on which it is invoked, while y.self() must create a new Python object which refers to the same Y instance.
89
90In Python:
91``
92>>> from back_references import *
93>>> x = X(1)
94>>> x2 = x.self()
95>>> x2 is x
961
97>>> (x.get(), x2.get())
98(1, 1)
99>>> x.set(10)
100>>> (x.get(), x2.get())
101(10, 10)
102>>>
103>>>
104>>> y = Y(2)
105>>> y2 = y.self()
106>>> y2 is y
1070
108>>> (y.get(), y2.get())
109(2, 2)
110>>> y.set(20)
111>>> (y.get(), y2.get())
112(20, 20)
113``
114[endsect]
115[endsect]
116