Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.


Header <boost/python/return_internal_reference.hpp>


Class Template return_internal_reference
Class Template return_internal_reference synopsis
Class return_internal_reference static functions


return_internal_reference instantiations are models of 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.


Class template return_internal_reference

return_internal_reference template parameters
Parameter Requirements Description Default
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. 1
Base A model of 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 CallPolicies. default_call_policies

Class template return_internal_reference synopsis

namespace boost { namespace python
   template <std::size_t owner_arg = 1, class Base = default_call_policies>
   struct return_internal_reference : Base
      static PyObject* postcall(PyObject*, PyObject* result);
      typedef reference_existing_object result_converter;

Class default_call_policies static functions

PyObject* postcall(PyObject* args, PyObject* result);
Requires: PyTuple_Check(args) != 0
Returns: with_custodian_and_ward_postcall::postcall(args, result)


C++ module definition

#include <boost/python/module.hpp>
#include <boost/python/class.hpp>
#include <boost/python/return_internal_reference.hpp>

class Bar
   Bar(int x) : x(x) {}
   int get_x() const { return x; }
   void set_x(int x) { this->x = x; }
   int x;

class Foo
   Foo(int x) : b(x) {}

   // Returns an internal reference
   Bar const& get_bar() const { return b; }

   Bar b;

using namespace boost::python;
      .def("get_x", &Bar::get_x)
      .def("set_x", &Bar::set_x)

   class_<Foo>("Foo", init<int>())
      .def("get_bar", &Foo::get_bar
          , return_internal_reference<>())

Python code

>>> from internal_refs import *
>>> f = Foo(3)
>>> b1 = f.get_bar()
>>> b2 = f.get_bar()
>>> b1.get_x()
>>> b2.get_x()
>>> b1.set_x(42)
>>> b2.get_x()

Revised 13 November, 2002

© Copyright Dave Abrahams 2002.