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
  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 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  57 PyTypeObject *pytalloc_GetObjectType(void)
  58
  59 Obtain a reference to the PyTypeObject for `pytalloc_Object`. The reference
  60 counter for the object will be incremented, so the caller will have to
  61 decrement it when it no longer needs it (using `Py_DECREF`).
  62
  63 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-
  64 int pytalloc_Check(PyObject *)
  65
  66 Check whether a specific object is a talloc Object. Returns non-zero if it is
  67 a pytalloc_Object and zero otherwise.
  68
  69 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  70 type *pytalloc_get_type(PyObject *py_obj, type)
  71
  72 Retrieve the pointer from a `pytalloc_Object` py_obj. type should be a
  73 C type, similar to a type passed to `talloc_get_type`.
  74
  75 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  76 pytalloc_get_ptr(PyObject *py_obj)
  77
  78 Retrieve the pointer from a `pytalloc_Object` py_obj. There is no
  79 type checking - use `pytalloc_get_type` if possible.
  80
  81 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  82 TALLOC_CTX *pytalloc_get_mem_ctx(PyObject *py_obj)
  83
  84 Retrieve the talloc context associated with a pytalloc_Object.
  85
  86 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  87 PyObject *pytalloc_steal_ex(PyTypeObject *py_type, TALLOC_CTX *mem_ctx, void *ptr)
  88
  89 Create a new Python wrapping object for a talloc pointer and context, with
  90 py_type as associated Python sub type object.
  91
  92 This will *not* increment the reference counter for the talloc context,
  93 so the caller should make sure such an increment has happened. When the Python
  94 object goes away, it will unreference the talloc context.
  95
  96 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  97 PyObject *pytalloc_steal(PyTypeObject *py_type, void *ptr)
  98
  99 Create a new Python wrapping object for a talloc pointer and context, with
 100 py_type as associated Python sub type object.
 101
 102 This will *not* increment the reference counter for the talloc context,
 103 so the caller should make sure such an increment has happened. When the Python
 104 object goes away, it will unreference the talloc context.
 105
 106 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 107 PyObject *pytalloc_reference_ex(PyTypeObject *py_type, TALLOC_CTX *mem_ctx, void *ptr)
 108
 109 Create a new Python wrapping object for a talloc pointer and context, with
 110 py_type as associated Python sub type object.
 111
 112 This will increment the reference counter for the talloc context.
 113
 114 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 115 PyObject *pytalloc_reference(PyTypeObject *py_type, void *talloc_ptr)
 116
 117 Create a new Python wrapping object for a talloc pointer, with
 118 py_type as associated Python sub type object. The pointer will also be used
 119 as the talloc context.
 120
 121 This will increment the reference counter for the talloc context.
 122
 123 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 124 PyObject *pytalloc_new(type, PyTypeObject *typeobj)
 125
 126 Create a new, empty pytalloc_Object with the specified Python type object. type
 127 should be a C type, similar to talloc_new().
 128
 129 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 130 PyObject *pytalloc_CObject_FromTallocPtr(void *);
 131
 132 Create a new pytalloc_Object for an abitrary talloc-maintained C pointer. This will
 133 use a generic VoidPtr Python type, which just provides an opaque object in
 134 Python. The caller is responsible for incrementing the talloc reference count before calling
 135 this function - it will dereference the talloc pointer when it is garbage collected.
 136
 137 This function is only available on Python 2.
 138
 139 Debug function for talloc in Python
 140 -----------------------------------
 141
 142 The "talloc" module in Python provides a couple of functions that can be used
 143 to debug issues with objects wrapped by pytalloc.
 144
 145 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 146 report_full(obj?)
 147
 148 Print a full report on a specific object or on all allocated objects by Python.
 149 Same behaviour as the `talloc_report_full()` function that is provided by
 150 C talloc.
 151
 152 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 153 enable_null_tracking()
 154
 155 This enables tracking of the NULL memory context without enabling leak
 156 reporting on exit. Useful for when you want to do your own leak
 157 reporting call via talloc_report_null_full().
 158
 159 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 160 pytalloc_total_blocks(obj?)
 161
 162 Return the talloc block count for all allocated objects or a specific object if
 163 specified.