|
|
Boost.PythonHeader <boost/python/ptr.hpp> |
pointer_wrapper
pointer_wrapper synopsis
pointer_wrapper types
pointer_wrapper constructors and destructor
pointer_wrapper observer functions
is_pointer_wrapper
is_pointer_wrapper synopsis
unwrap_pointer
unwrap_pointer synopsis
<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)
pointer_wrapperA "type envelope" which is returned by ptr(), used to indicate reference semantics for pointers passed to Python callbacks.
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;
};
}}
pointer_wrapper typestypedef Ptr type;The type of the pointer being wrapped.
pointer_wrapper constructors and
destructorexplicit pointer_wrapper(Ptr x);
Ptr is a pointer type.
x in a the pointer_wrapper<>.
pointer_wrapper observer
functionsoperator Ptr() const; Ptr get() const;
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.
is_pointer_wrapperA unary metafunction whose value is true iff its
argument is a pointer_wrapper<>.
is_pointer_wrapper synopsis
namespace boost { namespace python
{
template<class T> class is_pointer_wrapper
{
static unspecified value = ...;
};
}}
unwrap_pointerpointer_wrapper<>.
unwrap_pointer synopsis
namespace boost { namespace python
{
template<class T> class unwrap_pointer
{
typedef unspecified type;
};
}}
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));
}
...
Revised 13 November, 2002
© Copyright Dave Abrahams 2002. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)