1 [section boost/python/handle.hpp]
3 <boost/python/handle.hpp> provides class template `handle`, a smart pointer for managing reference-counted Python objects.
5 [section Class template `handle`]
6 `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 [link pod 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.
8 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`.
11 namespace boost { namespace python
16 typedef unspecified-member-function-pointer bool_type;
19 typedef T element_type;
21 public: // member functions
25 explicit handle(detail::borrowed<null_ok<Y> >* p);
28 explicit handle(null_ok<detail::borrowed<Y> >* p);
31 explicit handle(detail::borrowed<Y>* p);
34 explicit handle(null_ok<Y>* p);
37 explicit handle(Y* p);
41 handle& operator=(handle const& r);
44 handle& operator=(handle<Y> const & r); // never throws
48 handle(handle<Y> const& r);
50 handle(handle const& r);
52 T* operator-> () const;
53 T& operator* () const;
58 operator bool_type() const; // never throws
63 template <class T> struct null_ok;
64 namespace detail { template <class T> struct borrowed; }
67 [section Class template `handle` constructors and destructor]
68 ``virtual ~handle();``
70 [[Effects][`Py_XDECREF(upcast<PyObject*>(m_p))`]]
73 explicit handle(detail::borrowed<null_ok<Y> >* p);
77 ``Py_XINCREF(upcast<PyObject*>(p));
83 explicit handle(null_ok<detail::borrowed<Y> >* p);``
86 ``Py_XINCREF(upcast<PyObject*>(p));
92 explicit handle(detail::borrowed<Y>* p);``
95 ``Py_XINCREF(upcast<PyObject*>(p));
96 m_p = upcast<T*>(expect_non_null(p));
101 explicit handle(null_ok<Y>* p);
104 [[Effects][`m_p = upcast<T*>(p);`]]
108 explicit handle(Y* p);
111 [[Effects][`m_p = upcast<T*>(expect_non_null(p));`]]
117 [[Effects][`m_p = 0;`]]
120 template <typename Y>
121 handle(handle<Y> const& r);
122 handle(handle const& r);
125 [[Effects][m_p = r.m_p; Py_XINCREF(upcast<PyObject*>(m_p));]]
128 [section Class template `handle` modifiers]
130 handle& operator=(handle const& r);
132 handle& operator=(handle<Y> const & r); // never throws
135 [[Effects][`Py_XINCREF(upcast<PyObject*>(r.m_p)); Py_XDECREF( upcast<PyObject*>(m_p)); m_p = r.m_p;`]]
141 [[Effects][`T* x = m_p; m_p = 0; return x;`]]
147 [[Effects][`*this = handle<T>();`]]
150 [section Class template `handle` observers]
152 T* operator-> () const;
159 T& operator* () const;
165 operator bool_type() const; // never throws
168 [[Returns][`0` if `m_p == 0`, a pointer convertible to true otherwise.]]
172 [section Function `borrowed`]
175 detail::borrowed<T>* borrowed(T* p)
177 return (detail::borrowed<T>*)p;
181 [section Function `allow_null`]
184 null_ok<T>* allow_null(T* p)
186 return (null_ok<T>*)p;