]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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] |