ceph/src/boost/libs/python/doc/reference/has_back_reference.qbk

   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`]
   6 A unary metafunction whose value is true iff its argument is a `pointer_wrapper<>`.
   7 ``
   8 namespace boost { namespace python
   9 {
  10     template<class WrappedClass> class has_back_reference
  11     {
  12         typedef mpl::false_ type;
  13     };
  14 }}
  15 ``
  16
  17 A 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.
  20 Specializations 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]
  24 In 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
  32 using namespace boost::python;
  33 using boost::shared_ptr;
  34
  35 struct 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
  50 namespace boost { namespace python
  51 {
  52   template <>
  53   struct has_back_reference<X>
  54     : mpl::true_
  55   {};
  56 }}
  57
  58 struct 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
  68 shared_ptr<Y>
  69 Y_self(shared_ptr<Y> self) { return self; }
  70
  71 BOOST_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
  90 In Python:
  91 ``
  92 >>> from back_references import *
  93 >>> x = X(1)
  94 >>> x2 = x.self()
  95 >>> x2 is x
  96 1
  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
 107 0
 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]