|
Boost.PythonHeader <boost/python/handle.hpp> |
handle
handle
synopsishandle
constructors and destructorhandle
modifier functionshandle
observer functionsborrowed
allow_null
<boost/python/handle.hpp>
provides
class template handle
, a smart pointer for
managing reference-counted Python objects.
handle
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 tehe
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; 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; } }}
handle
constructors
and destructorvirtual ~handle();
Py_XDECREF(m_p)
template <class Y> explicit handle(detail::borrowed<null_ok<Y> >* p);
Py_XDECREF(m_p)
template <class Y> explicit handle(null_ok<detail::borrowed<Y> >* p);
m_p =
upcast<T*>(p);
template <class Y> explicit handle(detail::borrowed<Y>* p);
m_p =
upcast<T*>(expect_non_null(p));
template <class Y> explicit handle(null_ok<Y>* p);
Py_XINCREF(p); m_p =
upcast<T*>(p);
template <class Y> explicit handle(Y* p);
Py_XINCREF(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(m_p);
handle
modifiershandle& operator=(handle const& r); template<typename Y> handle& operator=(handle<Y> const & r); // never throws
Py_XINCREF(r.m_p); Py_XDECREF(m_p); m_p = r.m_p;
T* release();
T* x = m_p; m_p = 0;return
x;
handle
observersT* operator-> () const; T* get() const;
m_p;
T& operator* () const;
*m_p;
operator bool_type() const; // never throws
m_p == 0
, a pointer
convertible to true
otherwise.borrowed
templatedetail::borrowed * borrowed(T* p) { return (detail::borrowed *)p; }
allow_null
templatenull_ok * allow_null(T* p) { return (null_ok *)p; }
Revised 03 October, 2002
© Copyright Dave Abrahams 2002. All Rights Reserved.