talloc: use the system pytalloc-util for python3 as well
[sfrench/samba-autobuild/.git] / lib / talloc / pytalloc_guide.txt
1 Using talloc in Samba4
2 ======================
3
4 .. contents::
5
6 Jelmer Vernooij
7 August 2013
8
9 The most current version of this document is available at
10    http://samba.org/ftp/unpacked/talloc/pytalloc_guide.txt
11
12 pytalloc is a small library that provides glue for wrapping
13 talloc-allocated objects from C in Python objects.
14
15 What is pytalloc, and what is it not?
16 -------------------------------------
17
18 pytalloc is merely a helper library - it provides a convenient base type object
19 for objects that wrap talloc-maintained memory in C. It won't write your
20 bindings for you but it will make it easier to write C bindings that involve
21 talloc, and take away some of the boiler plate.
22
23 Python 3
24 --------
25
26 pytalloc can be used with Python 3. Usage from Python extension remains
27 the same, but for the C utilities, the library to link to is tagged with
28 Python's PEP3149 ABI tag, for example "pytalloc.cpython34m".
29 To make a build for Python 3, configure with PYTHON=/usr/bin/python3.
30 .
31 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
32 pytalloc_Object / pytalloc_BaseObject
33
34 This is the new base class that all Python objects that wrap talloc pointers
35 derive from. It is itself a subclass of the "Object" type that all objects
36 in Python derive from.
37
38 Note that you will almost never create objects of the pytalloc_Object type
39 itself, as they are just opaque pointers that can not be accessed from
40 Python. A common pattern is other objects that subclass pytalloc_Object and
41 rely on it for their memory management.
42
43 Each `pytalloc_Object` wraps two core of information - a talloc context
44 and a pointer. The pointer is the actual data that is wrapped. The talloc
45 context is used for memory management purposes only; when the wrapping Python object
46 goes away, it unlinks the talloc context. The talloc context pointer and the ptr
47 can (and often do) have the same value.
48
49 Each pytalloc_Object has a custom __repr__ implementation that
50 describes that it is a talloc object and the location of the
51 pointer it is wrapping. it also has a custom __cmp__/__eq__/__neq__ method that
52 compares the pointers the object is wrapping rather than the objects
53 themselves (since there can be multiple objects that wrap the same talloc
54 pointer).
55
56 It is preferred to use pytalloc_BaseObject as this implementation
57 exposes less in the C ABI and correctly supports pointers in C arrays
58 in the way needed by PIDL.
59
60 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
61 PyTypeObject *pytalloc_GetObjectType(void)
62
63 Obtain a pointer to the PyTypeObject for `pytalloc_Object`. The
64 reference counter for the object will be NOT incremented, so the
65 caller MUST NOT decrement it when it no longer needs it (eg by using
66 `Py_DECREF`).
67
68 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
69 PyTypeObject *pytalloc_GetBaseObjectType(void)
70
71 Obtain a pointer to the PyTypeObject for `pytalloc_BaseObject`. The
72 reference counter for the object will be NOT incremented, so the
73 caller MUST NOT decrement it when it no longer needs it (eg by using
74 `Py_DECREF`).
75
76 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
77 int pytalloc_BaseObject_PyType_Ready(PyTypeObject *type);
78
79 Wrapper for PyType_Ready() that will set the correct values into
80 the PyTypeObject to create a BaseObject
81
82 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-
83 int pytalloc_Check(PyObject *)
84
85 Check whether a specific object is a talloc Object. Returns non-zero if it is
86 a pytalloc_Object and zero otherwise.
87
88 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-
89 int pytalloc_BaseObject_Check(PyObject *)
90
91 Check whether a specific object is a talloc BaseObject. Returns non-zero if it is
92 a pytalloc_BaseObject and zero otherwise.
93
94 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
95 int pytalloc_check_type(PyObject *py_obj, type)
96
97 Check if the object based on `pytalloc_*Object` py_obj. type should be a
98 C type, similar to a type passed to `talloc_get_type`.
99 This can be used as a check before using pytalloc_get_type()
100 or an alternative codepath. Returns non-zero if it is
101 an object of the expected type and zero otherwise.
102
103 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
104 type *pytalloc_get_type(PyObject *py_obj, type)
105
106 Retrieve the pointer from a `pytalloc_Object` py_obj. type should be a
107 C type, similar to a type passed to `talloc_get_type`.
108
109 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
110 pytalloc_get_ptr(PyObject *py_obj)
111
112 Retrieve the pointer from a `pytalloc_Object` or `pytalloc_BaseObject`
113 py_obj. There is no type checking - use `pytalloc_get_type` if
114 possible.
115
116 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
117 TALLOC_CTX *pytalloc_get_mem_ctx(PyObject *py_obj)
118
119 Retrieve the talloc context associated with a pytalloc_Object or pytalloc_BaseObject.
120
121 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
122 PyObject *pytalloc_steal_ex(PyTypeObject *py_type, TALLOC_CTX *mem_ctx, void *ptr)
123
124 Create a new Python wrapping object for a talloc pointer and context, with
125 py_type as associated Python sub type object. This typically used
126 when `mem_ctx` and `ptr` differ, e.g. a pointer to an array element.
127 `pytalloc_get_ptr()` can be used to get the pointer out of the object again.
128
129 This will *not* increment the reference counter for the talloc context,
130 so the caller should make sure such an increment has happened. When the Python
131 object goes away, it will unreference the talloc context.
132
133 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
134 PyObject *pytalloc_steal(PyTypeObject *py_type, void *ptr)
135
136 Create a new Python wrapping object for a talloc pointer and context, with
137 py_type as associated Python sub type object. The pointer will also be used
138 as the talloc context. `pytalloc_get_type()` can be used to get
139 the pointer out of the object again.
140
141 This will *not* increment the reference counter for the talloc context,
142 so the caller should make sure such an increment has happened. When the Python
143 object goes away, it will unreference the talloc context.
144
145 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
146 PyObject *pytalloc_reference_ex(PyTypeObject *py_type, TALLOC_CTX *mem_ctx, void *ptr)
147
148 Create a new Python wrapping object for a talloc pointer and context, with
149 py_type as associated Python sub type object. This typically used
150 when `mem_ctx` and `ptr` differ, e.g. a pointer to an array element.
151 `pytalloc_get_ptr()` can be used to get the pointer out of the object again.
152
153 This will increment the reference counter for the talloc context.
154
155 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
156 PyObject *pytalloc_reference(PyTypeObject *py_type, void *talloc_ptr)
157
158 Create a new Python wrapping object for a talloc pointer, with
159 py_type as associated Python sub type object. The pointer will also be used
160 as the talloc context. `pytalloc_get_type()` can be used to get
161 the pointer out of the object again.
162
163 This will increment the reference counter for the talloc context.
164
165 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
166 PyObject *pytalloc_new(type, PyTypeObject *typeobj)
167
168 Create a new, empty pytalloc_Object with the specified Python type object. type
169 should be a C type, similar to talloc_new().
170
171 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
172 PyObject *pytalloc_GenericObject_steal_ex(void *ptr)
173
174 Create a new Python wrapping object for a generic talloc pointer,
175 as sub type of `pytalloc_BaseObject`. This typically used
176 when `mem_ctx` and `ptr` differ, e.g. a pointer to an array element.
177 `pytalloc_get_ptr()` can be used to get the pointer out of the object again.
178
179 This will *not* increment the reference counter for the talloc context,
180 so the caller should make sure such an increment has happened. When the Python
181 object goes away, it will unreference the talloc context.
182
183 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
184 PyObject *pytalloc_GenericObject_steal(void *ptr)
185
186 Create a new Python wrapping object for a generic talloc pointer,
187 as sub type of `pytalloc_BaseObject`. The pointer will also be used
188 as the talloc context. `pytalloc_get_type()` can be used to get
189 the pointer out of the object again.
190
191 This will *not* increment the reference counter for the talloc context,
192 so the caller should make sure such an increment has happened. When the Python
193 object goes away, it will unreference the talloc context.
194
195 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
196 PyObject *pytalloc_GenericObject_reference_ex(void *ptr)
197
198 Create a new Python wrapping object for a generic talloc pointer,
199 as sub type of `pytalloc_BaseObject`. This typically used
200 when `mem_ctx` and `ptr` differ, e.g. a pointer to an array element.
201 `pytalloc_get_ptr()` can be used to get the pointer out of the object again.
202
203 This will increment the reference counter for the talloc context.
204
205 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
206 PyObject *pytalloc_GenericObject_reference(void *ptr)
207
208 Create a new Python wrapping object for a generic talloc pointer,
209 as sub type of `pytalloc_BaseObject`. The pointer will also be used
210 as the talloc context. `pytalloc_get_type()` can be used to get
211 the pointer out of the object again.
212
213 This will increment the reference counter for the talloc context.
214
215 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
216 DEPRECATED! PyObject *pytalloc_CObject_FromTallocPtr(void *);
217
218 Create a new pytalloc_Object for an abitrary talloc-maintained C pointer. This will
219 use a generic VoidPtr Python type, which just provides an opaque object in
220 Python. The caller is responsible for incrementing the talloc reference count before calling
221 this function - it will dereference the talloc pointer when it is garbage collected.
222
223 This function is deprecated and only available on Python 2.
224 Use pytalloc_GenericObject_{reference,steal}[_ex]() instead.
225
226 Debug function for talloc in Python
227 -----------------------------------
228
229 The "talloc" module in Python provides a couple of functions that can be used
230 to debug issues with objects wrapped by pytalloc.
231
232 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
233 report_full(obj?)
234
235 Print a full report on a specific object or on all allocated objects by Python.
236 Same behaviour as the `talloc_report_full()` function that is provided by
237 C talloc.
238
239 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
240 enable_null_tracking()
241
242 This enables tracking of the NULL memory context without enabling leak
243 reporting on exit. Useful for when you want to do your own leak
244 reporting call via talloc_report_null_full().
245
246 This must be done in the top level script, not an imported module.
247
248 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
249 pytalloc_total_blocks(obj?)
250
251 Return the talloc block count for all allocated objects or a specific object if
252 specified.