Boost C++ Libraries

...one 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.

C++ Boost

Boost.Python

Header <boost/python/reference_existing_object.hpp>


Contents

Classes
Class reference_existing_object
Class reference_existing_object synopsis
Class reference_existing_object metafunctions
Example

Classes

Class reference_existing_object

reference_existing_object is a model of ResultConverterGenerator which can be used to wrap C++ functions which return a reference or pointer to a C++ object. When the wrapped function is called, the value referenced by its return value is not copied. A new Python object is created which contains a pointer to the referent, and no attempt is made to ensure that the lifetime of the referent is at least as long as that of the corresponding Python object. Thus, it can be highly dangerous to use reference_existing_object without additional lifetime management from such models of CallPolicies as with_custodian_and_ward. This class is used in the implementation of return_internal_reference.

Class reference_existing_object synopsis

namespace boost { namespace python
{
    struct reference_existing_object
    {
        template <class T> struct apply;
    };
}}

Class reference_existing_object metafunctions

template <class T> struct apply
Requires: T is U& or U*for some U.
Returns: typedef to_python_indirect<T,V> type, where V is a HolderObjectGenerator which constructs an instance holder containing an unowned U* pointing to the referent of the wrapped function's return value.

Example

In C++:

#include <boost/python/module.hpp>
#include <boost/python/class.hpp>
#include <boost/python/reference_existing_object.hpp>
#include <boost/python/return_value_policy.hpp>
#include <utility>

// classes to wrap
struct Singleton
{
   Singleton() : x(0) {}

   int exchange(int n)  // set x and return the old value
   {
        std::swap(n, x);
        return n;
   }

   int x;
};

Singleton& get_it()
{
   static Singleton just_one;
   return just_one;
}

// Wrapper code
using namespace boost::python;
BOOST_PYTHON_MODULE(singleton)
{
    def("get_it", get_it,
        return_value_policy<reference_existing_object>());

    class_<Singleton>("Singleton")
       .def("exchange", &Singleton::exchange)
       ;
}
In Python:
>>> import singleton
>>> s1 = singleton.get_it()  
>>> s2 = singleton.get_it()
>>> id(s1) == id(s2)  # s1 and s2 are not the same object
0
>>> s1.exchange(42)   # but they reference the same C++ Singleton
0
>>> s2.exchange(99)
42

Revised 13 November, 2002

© Copyright Dave Abrahams 2002. All Rights Reserved.