Boost.Python

Contents

Introduction

Functions

ptr

Classes

Class template pointer_wrapper

Class template pointer_wrapper synopsis

Class pointer_wrapper types

Class pointer_wrapper constructors and destructor

Class pointer_wrapper observer functions

Metafunctions

Class template is_pointer_wrapper

Class template is_pointer_wrapper synopsis

Class template unwrap_pointer

Class template unwrap_pointer synopsis

Example(s)

Introduction

<boost/python/ptr.hpp> defines the ptr() function template, which allows users to specify how to convert C++ pointer values to python in the context of implementing overridable virtual functions, invoking Python callable objects, or explicitly converting C++ objects to Python. Normally, when passing pointers to Python callbacks, the pointee is copied to ensure that the Python object never holds a dangling reference. To specify that the new Python object should merely contain a copy of a pointer p, the user can pass ptr(p) instead of passing p directly. This interface is meant to mirror the use of boost::ref(), which can be similarly used to prevent copying of referents.

ptr(p) returns an instance of pointer_wrapper<>, which can be detected using the is_pointer_wrapper<> metafunction; unwrap_pointer<> is a metafunction which extracts the original pointer type from a pointer_wrapper<>. These classes can be thought of as implementation details.

Functions

template <class T>
pointer_wrapper<T> ptr(T x);

Requires: T is a pointer type.

Returns: pointer_wrapper<T>(x)

Throws: nothing.

Classes

Class template pointer_wrapper

A "type envelope" which is returned by ptr(), used to indicate reference semantics for pointers passed to Python callbacks.

Class pointer_wrapper synopsis

namespace boost { namespace python
{
    template<class Ptr> class pointer_wrapper
    { 
     public:
        typedef Ptr type;

        explicit pointer_wrapper(Ptr x);
        operator Ptr() const;
        Ptr get() const;
    };
}}

Class template pointer_wrapper types

typedef Ptr type;

Class template pointer_wrapper constructors and destructor

explicit pointer_wrapper(Ptr x);

Requires: Ptr is a pointer type.

Effects: Stores x in a the pointer_wrapper<>.

Throws: nothing.

Class template pointer_wrapper observer functions

operator Ptr() const;
Ptr get() const;

Returns: a copy of the stored pointer.

Rationale: pointer_wrapper is intended to be a stand-in for the actual pointer type, but sometimes it's better to have an explicit way to retrieve the pointer.

Metafunctions

Class template is_pointer_wrapper

A unary metafunction whose value is true iff its argument is a pointer_wrapper<>.

Class template is_pointer_wrapper synopsis

namespace boost { namespace python
{
    template<class T> class is_pointer_wrapper
    { 
        static unspecified value = ...;
    };
}}

Returns: true iff T is a specialization of pointer_wrapper<>.

value is an integral constant convertible to bool of unspecified type

Class template unwrap_pointer

Class template unwrap_pointer synopsis

namespace boost { namespace python
{
    template<class T> class unwrap_pointer
    { 
        typedef unspecified type;
    };
}}

Returns: T::type if T is a specialization of pointer_wrapper<>, T otherwise

Example(s)

#include <boost/python/call.hpp>
#include <boost/python/ptr.hpp>

class expensive_to_copy
{
   ...
};

void pass_as_arg(expensive_to_copy* x, PyObject* f)
{
   // call the Python function f, passing a Python object built around
   // which refers to *x by-pointer.
   //
   // *** Note: ensuring that *x outlives the argument to f() is    ***
   // *** up to the user! Failure to do so could result in a crash! ***

   boost::python::call<void>(f, ptr(x));
}
...

Revised 13 November, 2002

© Copyright Dave Abrahams 2002.