1[section boost/python/handle.hpp] 2[section Introduction] 3<boost/python/handle.hpp> provides class template `handle`, a smart pointer for managing reference-counted Python objects. 4[endsect] 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. 7 8In 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`. 9 10`` 11namespace boost { namespace python 12{ 13 template <class T> 14 class handle 15 { 16 typedef unspecified-member-function-pointer bool_type; 17 18 public: // types 19 typedef T element_type; 20 21 public: // member functions 22 ~handle(); 23 24 template <class Y> 25 explicit handle(detail::borrowed<null_ok<Y> >* p); 26 27 template <class Y> 28 explicit handle(null_ok<detail::borrowed<Y> >* p); 29 30 template <class Y> 31 explicit handle(detail::borrowed<Y>* p); 32 33 template <class Y> 34 explicit handle(null_ok<Y>* p); 35 36 template <class Y> 37 explicit handle(Y* p); 38 39 handle(); 40 41 handle& operator=(handle const& r); 42 43 template<typename Y> 44 handle& operator=(handle<Y> const & r); // never throws 45 46 47 template <typename Y> 48 handle(handle<Y> const& r); 49 50 handle(handle const& r); 51 52 T* operator-> () const; 53 T& operator* () const; 54 T* get() const; 55 void reset(); 56 T* release(); 57 58 operator bool_type() const; // never throws 59 private: 60 T* m_p; 61 }; 62 63 template <class T> struct null_ok; 64 namespace detail { template <class T> struct borrowed; } 65}} 66`` 67[section Class template `handle` constructors and destructor] 68``virtual ~handle();`` 69[variablelist 70[[Effects][`Py_XDECREF(upcast<PyObject*>(m_p))`]] 71] 72``template <class Y> 73explicit handle(detail::borrowed<null_ok<Y> >* p); 74`` 75[variablelist 76[[Effects][ 77``Py_XINCREF(upcast<PyObject*>(p)); 78m_p = upcast<T*>(p); 79`` 80]] 81] 82``template <class Y> 83explicit handle(null_ok<detail::borrowed<Y> >* p);`` 84[variablelist 85[[Effects][ 86``Py_XINCREF(upcast<PyObject*>(p)); 87 m_p = upcast<T*>(p); 88`` 89]] 90] 91``template <class Y> 92explicit handle(detail::borrowed<Y>* p);`` 93[variablelist 94[[Effects][ 95``Py_XINCREF(upcast<PyObject*>(p)); 96 m_p = upcast<T*>(expect_non_null(p)); 97`` 98]] 99] 100``template <class Y> 101explicit handle(null_ok<Y>* p); 102`` 103[variablelist 104[[Effects][`m_p = upcast<T*>(p);`]] 105] 106`` 107template <class Y> 108explicit handle(Y* p); 109`` 110[variablelist 111[[Effects][`m_p = upcast<T*>(expect_non_null(p));`]] 112] 113`` 114handle(); 115`` 116[variablelist 117[[Effects][`m_p = 0;`]] 118] 119`` 120template <typename Y> 121handle(handle<Y> const& r); 122handle(handle const& r); 123`` 124[variablelist 125[[Effects][m_p = r.m_p; Py_XINCREF(upcast<PyObject*>(m_p));]] 126] 127[endsect] 128[section Class template `handle` modifiers] 129`` 130handle& operator=(handle const& r); 131template<typename Y> 132handle& operator=(handle<Y> const & r); // never throws 133`` 134[variablelist 135[[Effects][`Py_XINCREF(upcast<PyObject*>(r.m_p)); Py_XDECREF( upcast<PyObject*>(m_p)); m_p = r.m_p;`]] 136] 137`` 138T* release(); 139`` 140[variablelist 141[[Effects][`T* x = m_p; m_p = 0; return x;`]] 142] 143`` 144void reset(); 145`` 146[variablelist 147[[Effects][`*this = handle<T>();`]] 148] 149[endsect] 150[section Class template `handle` observers] 151`` 152T* operator-> () const; 153T* get() const; 154`` 155[variablelist 156[[Returns][`m_p;`]] 157] 158`` 159T& operator* () const; 160`` 161[variablelist 162[[Returns][`*m_p;`]] 163] 164`` 165operator bool_type() const; // never throws 166`` 167[variablelist 168[[Returns][`0` if `m_p == 0`, a pointer convertible to true otherwise.]] 169] 170[endsect] 171[endsect] 172[section Function `borrowed`] 173`` 174template <class T> 175detail::borrowed<T>* borrowed(T* p) 176{ 177 return (detail::borrowed<T>*)p; 178} 179`` 180[endsect] 181[section Function `allow_null`] 182`` 183template <class T> 184null_ok<T>* allow_null(T* p) 185{ 186 return (null_ok<T>*)p; 187} 188`` 189[endsect] 190[endsect] 191