...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
<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.
template <class T> pointer_wrapper<T> ptr(T x);
T is a pointer type.
pointer_wrapper<T>(x)
nothing.
A "type envelope" which is returned by ptr()
, used to indicate reference semantics
for pointers passed to Python callbacks.
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; }; }}
explicit pointer_wrapper(Ptr x);
Ptr
is a pointer
type
Stores x
in a the
pointer_wrapper<>
.
nothing.
operator Ptr() const; Ptr get() const;
a copy of the stored pointer.
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.
A unary metafunction whose value is true iff its argument is a pointer_wrapper<>.
namespace boost { namespace python { template<class T> class is_pointer_wrapper { static unspecified value = ...; }; }}
true
iff T
is a specialization of pointer_wrapper<>
.
value is an integral constant convertible to bool of unspecified
type
A unary metafunction which extracts the wrapped pointer type from a specialization of pointer_wrapper<>.
namespace boost { namespace python { template<class T> class unwrap_pointer { typedef unspecified type; }; }}
T::type
if T
is a specialization of pointer_wrapper<>
, T
otherwise
This example illustrates the use of ptr() to prevent an object from being copied:
#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)); } ...