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

   1 [section boost/python/return_internal_reference.hpp]
   2 [section Introduction]
   3 `return_internal_reference` instantiations are models of [link concepts.callpolicies `CallPolicies`] 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 (`*this`) of a wrapped member function.
   4 [endsect]
   5 [section Class template `return_internal_reference`]
   6 [table
   7  [[Parameter][Requirements][Description][Default]]
   8  [[owner_arg][A positive compile-time constant of type `std::size_t`.][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 (`*this`). Note that if the target Python object type doesn't support weak references, a Python TypeError exception will be raised when the function being wrapped is called.][]]
   9  [[Base][A model of [link concepts.callpolicies `CallPolicies`]][Used for policy composition. Any `result_converter` it supplies will be overridden by `return_internal_reference`, but its `precall` and `postcall` policies are composed as described here [link concepts.callpolicies `CallPolicies`].][default_call_policies]]
  10 ]
  11 ``
  12 namespace boost { namespace python
  13 {
  14    template <std::size_t owner_arg = 1, class Base = default_call_policies>
  15    struct return_internal_reference : Base
  16    {
  17       static PyObject* postcall(PyObject*, PyObject* result);
  18       typedef reference_existing_object result_converter;
  19    };
  20 }}
  21 ``
  22 [endsect]
  23 [section Class `return_internal_reference` static functions]
  24 ``PyObject* postcall(PyObject* args, PyObject* result);``
  25 [variablelist
  26 [[Requires][`PyTuple_Check(args) != 0`]]
  27 [[Returns][[link function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st `with_custodian_and_ward_postcall::postcall(args, result)`]]]
  28 ]
  29 [endsect]
  30 [section Example]
  31 C++ module definition:
  32 ``
  33 #include <boost/python/module.hpp>
  34 #include <boost/python/class.hpp>
  35 #include <boost/python/return_internal_reference.hpp>
  36
  37 class Bar
  38 {
  39  public:
  40    Bar(int x) : x(x) {}
  41    int get_x() const { return x; }
  42    void set_x(int x) { this->x = x; }
  43  private:
  44    int x;
  45 };
  46
  47 class Foo
  48 {
  49  public:
  50    Foo(int x) : b(x) {}
  51
  52    // Returns an internal reference
  53    Bar const& get_bar() const { return b; }
  54
  55  private:
  56    Bar b;
  57 };
  58
  59 using namespace boost::python;
  60 BOOST_PYTHON_MODULE(internal_refs)
  61 {
  62    class_<Bar>("Bar", init<int>())
  63       .def("get_x", &Bar::get_x)
  64       .def("set_x", &Bar::set_x)
  65       ;
  66
  67    class_<Foo>("Foo", init<int>())
  68       .def("get_bar", &Foo::get_bar
  69           , return_internal_reference<>())
  70       ;
  71 }
  72 ``
  73 Python code:
  74 ``
  75 >>> from internal_refs import *
  76 >>> f = Foo(3)
  77 >>> b1 = f.get_bar()
  78 >>> b2 = f.get_bar()
  79 >>> b1.get_x()
  80 3
  81 >>> b2.get_x()
  82 3
  83 >>> b1.set_x(42)
  84 >>> b2.get_x()
  85 42
  86 ``
  87 [endsect]
  88 [endsect]