...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/handle.hpp> provides class template handle
,
a smart pointer for managing reference-counted Python objects.
handle
is a smart pointer
to a Python object type; it holds a pointer of type T*
, where T
is its template parameter. T must be either a type derived from PyObject
or a POD
type whose initial sizeof(PyObject)
bytes are layout-compatible with PyObject
. Use handle<>
at the boundary between the Python/'C'
API and high-level code; prefer object for a generalized interface to Python
objects.
In this document, the term "upcast" refers to an operation which
converts a pointer Y*
to a base class pointer T*
via
static_cast<T*>
if Y
is derived from T
, or via C-style cast (T*
) if
it is not. However, in the latter case the "upcast" is ill-formed
if the initial sizeof(PyObject)
bytes of Y
are not layout-compatible
with PyObject
.
namespace boost { namespace python { template <class T> class handle { typedef unspecified-member-function-pointer bool_type; public: // types typedef T element_type; public: // member functions ~handle(); template <class Y> explicit handle(detail::borrowed<null_ok<Y> >* p); template <class Y> explicit handle(null_ok<detail::borrowed<Y> >* p); template <class Y> explicit handle(detail::borrowed<Y>* p); template <class Y> explicit handle(null_ok<Y>* p); template <class Y> explicit handle(Y* p); handle(); handle& operator=(handle const& r); template<typename Y> handle& operator=(handle<Y> const & r); // never throws template <typename Y> handle(handle<Y> const& r); handle(handle const& r); T* operator-> () const; T& operator* () const; T* get() const; void reset(); T* release(); operator bool_type() const; // never throws private: T* m_p; }; template <class T> struct null_ok; namespace detail { template <class T> struct borrowed; } }}
virtual ~handle();
Py_XDECREF(upcast<PyObject*>(m_p))
template <class Y> explicit handle(detail::borrowed<null_ok<Y> >* p);
Py_XINCREF(upcast<PyObject*>(p)); m_p = upcast<T*>(p);
template <class Y> explicit handle(null_ok<detail::borrowed<Y> >* p);
Py_XINCREF(upcast<PyObject*>(p)); m_p = upcast<T*>(p);
template <class Y> explicit handle(detail::borrowed<Y>* p);
Py_XINCREF(upcast<PyObject*>(p)); m_p = upcast<T*>(expect_non_null(p));
template <class Y> explicit handle(null_ok<Y>* p);
m_p =
upcast<T*>(p);
template <class Y> explicit handle(Y* p);
m_p =
upcast<T*>(expect_non_null(p));
handle();
m_p =
0;
template <typename Y> handle(handle<Y> const& r); handle(handle const& r);
m_p = r.m_p; Py_XINCREF(upcast<PyObject*>(m_p));
handle& operator=(handle const& r); template<typename Y> handle& operator=(handle<Y> const & r); // never throws
Py_XINCREF(upcast<PyObject*>(r.m_p));
Py_XDECREF(
upcast<PyObject*>(m_p));
m_p =
r.m_p;
T* release();
T*
x =
m_p;
m_p =
0;
return x;
void reset();
*this
= handle<T>();
T* operator-> () const; T* get() const;
m_p;
T& operator* () const;
*m_p;
operator bool_type() const; // never throws
0
if m_p ==
0
, a pointer convertible
to true otherwise.
template <class T> detail::borrowed<T>* borrowed(T* p) { return (detail::borrowed<T>*)p; }
template <class T> null_ok<T>* allow_null(T* p) { return (null_ok<T>*)p; }