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.