###

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