ceph/src/boost/libs/python/doc/reference/handle.qbk

   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
   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`.
   9
  10 ``
  11 namespace 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>
  73 explicit handle(detail::borrowed<null_ok<Y> >* p);
  74 ``
  75 [variablelist
  76 [[Effects][
  77 ``Py_XINCREF(upcast<PyObject*>(p));
  78 m_p = upcast<T*>(p);
  79 ``
  80 ]]
  81 ]
  82 ``template <class Y>
  83 explicit 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>
  92 explicit 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>
 101 explicit handle(null_ok<Y>* p);
 102 ``
 103 [variablelist
 104 [[Effects][`m_p = upcast<T*>(p);`]]
 105 ]
 106 ``
 107 template <class Y>
 108 explicit handle(Y* p);
 109 ``
 110 [variablelist
 111 [[Effects][`m_p = upcast<T*>(expect_non_null(p));`]]
 112 ]
 113 ``
 114 handle();
 115 ``
 116 [variablelist
 117 [[Effects][`m_p = 0;`]]
 118 ]
 119 ``
 120 template <typename Y>
 121 handle(handle<Y> const& r);
 122 handle(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 ``
 130 handle& operator=(handle const& r);
 131 template<typename Y>
 132 handle& 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 ``
 138 T* release();
 139 ``
 140 [variablelist
 141 [[Effects][`T* x = m_p; m_p = 0; return x;`]]
 142 ]
 143 ``
 144 void reset();
 145 ``
 146 [variablelist
 147 [[Effects][`*this = handle<T>();`]]
 148 ]
 149 [endsect]
 150 [section Class template `handle` observers]
 151 ``
 152 T* operator-> () const;
 153 T* get() const;
 154 ``
 155 [variablelist
 156 [[Returns][`m_p;`]]
 157 ]
 158 ``
 159 T& operator* () const;
 160 ``
 161 [variablelist
 162 [[Returns][`*m_p;`]]
 163 ]
 164 ``
 165 operator 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 ``
 174 template <class T>
 175 detail::borrowed<T>* borrowed(T* p)
 176 {
 177     return (detail::borrowed<T>*)p;
 178 }
 179 ``
 180 [endsect]
 181 [section Function `allow_null`]
 182 ``
 183 template <class T>
 184 null_ok<T>* allow_null(T* p)
 185 {
 186     return (null_ok<T>*)p;
 187 }
 188 ``
 189 [endsect]
 190 [endsect]