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 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  24 pytalloc_Object
  25
  26 This is the new base class that all Python objects that wrap talloc pointers
  27 derive from. It is itself a subclass of the "Object" type that all objects
  28 in Python derive from.
  29
  30 Note that you will almost never create objects of the pytalloc_Object type
  31 itself, as they are just opaque pointers that can not be accessed from
  32 Python. A common pattern is other objects that subclass pytalloc_Object and
  33 rely on it for their memory management.
  34
  35 Each `pytalloc_Object` wraps two core of information - a talloc context
  36 and a pointer. The pointer is the actual data that is wrapped. The talloc
  37 context is used for memory management purposes only; when the wrapping Python object
  38 goes away, it unlinks the talloc context. The talloc context pointer and the ptr
  39 can (and often do) have the same value.
  40
  41 Each pytalloc_Object has a custom __repr__ implementation that
  42 describes that it is a talloc object and the location of the
  43 pointer it is wrapping. it also has a custom __cmp__/__eq__/__neq__ method that
  44 compares the pointers the object is wrapping rather than the objects
  45 themselves (since there can be multiple objects that wrap the same talloc
  46 pointer).
  47
  48 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  49 PyTypeObject *pytalloc_GetObjectType(void)
  50
  51 Obtain a reference to the PyTypeObject for `pytalloc_Object`. The reference
  52 counter for the object will be incremented, so the caller will have to
  53 decrement it when it no longer needs it (using `Py_DECREF`).
  54
  55 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==-=-=-=-=-=-=-=-=-=-=-
  56 int pytalloc_Check(PyObject *)
  57
  58 Check whether a specific object is a talloc Object. Returns non-zero if it is
  59 a pytalloc_Object and zero otherwise.
  60
  61 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  62 type *pytalloc_get_type(PyObject *py_obj, type)
  63
  64 Retrieve the pointer from a `pytalloc_Object` py_obj. type should be a
  65 C type, similar to a type passed to `talloc_get_type`.
  66
  67 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  68 pytalloc_get_ptr(PyObject *py_obj)
  69
  70 Retrieve the pointer from a `pytalloc_Object` py_obj. There is no
  71 type checking - use `pytalloc_get_type` if possible.
  72
  73 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  74 TALLOC_CTX *pytalloc_get_mem_ctx(PyObject *py_obj)
  75
  76 Retrieve the talloc context associated with a pytalloc_Object.
  77
  78 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  79 PyObject *pytalloc_steal_ex(PyTypeObject *py_type, TALLOC_CTX *mem_ctx, void *ptr)
  80
  81 Create a new Python wrapping object for a talloc pointer and context, with
  82 py_type as associated Python sub type object.
  83
  84 This will *not* increment the reference counter for the talloc context,
  85 so the caller should make sure such an increment has happened. When the Python
  86 object goes away, it will unreference the talloc context.
  87
  88 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  89 PyObject *pytalloc_steal(PyTypeObject *py_type, void *ptr)
  90
  91 Create a new Python wrapping object for a talloc pointer and context, with
  92 py_type as associated Python sub type object.
  93
  94 This will *not* increment the reference counter for the talloc context,
  95 so the caller should make sure such an increment has happened. When the Python
  96 object goes away, it will unreference the talloc context.
  97
  98 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  99 PyObject *pytalloc_reference_ex(PyTypeObject *py_type, TALLOC_CTX *mem_ctx, void *ptr)
 100
 101 Create a new Python wrapping object for a talloc pointer and context, with
 102 py_type as associated Python sub type object.
 103
 104 This will increment the reference counter for the talloc context.
 105
 106 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 107 PyObject *pytalloc_reference(PyTypeObject *py_type, void *talloc_ptr)
 108
 109 Create a new Python wrapping object for a talloc pointer, with
 110 py_type as associated Python sub type object. The pointer will also be used
 111 as the talloc context.
 112
 113 This will increment the reference counter for the talloc context.
 114
 115 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 116 PyObject *pytalloc_new(type, PyTypeObject *typeobj)
 117
 118 Create a new, empty pytalloc_Object with the specified Python type object. type
 119 should be a C type, similar to talloc_new().
 120
 121 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 122 PyObject *pytalloc_CObject_FromTallocPtr(void *);
 123
 124 Create a new pytalloc_Object for an abitrary talloc-maintained C pointer. This will
 125 use a generic VoidPtr Python type, which just provides an opaque object in
 126 Python. The caller is responsible for incrementing the talloc reference count before calling
 127 this function - it will dereference the talloc pointer when it is garbage collected.
 128
 129 Debug function for talloc in Python
 130 -----------------------------------
 131
 132 The "talloc" module in Python provides a couple of functions that can be used
 133 to debug issues with objects wrapped by pytalloc.
 134
 135 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 136 report_full(obj?)
 137
 138 Print a full report on a specific object or on all allocated objects by Python.
 139 Same behaviour as the `talloc_report_full()` function that is provided by
 140 C talloc.
 141
 142 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 143 enable_null_tracking()
 144
 145 This enables tracking of the NULL memory context without enabling leak
 146 reporting on exit. Useful for when you want to do your own leak
 147 reporting call via talloc_report_null_full().
 148
 149 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 150 pytalloc_total_blocks(obj?)
 151
 152 Return the talloc block count for all allocated objects or a specific object if
 153 specified.