lib/talloc/doc/tutorial_context.dox

   1 /**
   2 @page libtalloc_context Chapter 1: Talloc context
   3 @section context Talloc context
   4
   5 The talloc context is the most important part of this library and is
   6 responsible for every single feature of this memory allocator. It is a logical
   7 unit which represents a memory space managed by talloc.
   8
   9 From the programmer's point of view, the talloc context is completely
  10 equivalent to a pointer that would be returned by the memory routines from the
  11 C standard library. This means that every context that is returned from the
  12 talloc library can be used directly in functions that do not use talloc
  13 internally. For example we can do the following:
  14
  15 @code
  16 char *str1 = strdup("I am NOT a talloc context");
  17 char *str2 = talloc_strdup(NULL, "I AM a talloc context");
  18
  19 printf("%d\n", strcmp(str1, str2) == 0);
  20
  21 free(str1);
  22 talloc_free(str2); /* we can not use free() on str2 */
  23 @endcode
  24
  25 This is possible because the context is internally handled as a special
  26 fixed-length structure called talloc chunk. Each chunk stores context metadata
  27 followed by the memory space requested by the programmer. When a talloc
  28 function returns a context (pointer), it will in fact return a pointer to the user
  29 space portion of the talloc chunk. If we to manipulate this context using
  30 talloc functions, the talloc library transforms the user-space pointer back to
  31 the starting address of the chunk. This is also the reason why we were unable
  32 to use <code>free(str2)</code> in the previous example - because
  33 <code>str2</code> does not point at the beginning of the allocated block of
  34 memory. This is illustrated on the next image:
  35
  36 @image html context.png
  37
  38 The type TALLOC_CTX is defined in talloc.h to identify a talloc context in
  39 function parameters. However, this type is just an alias for <code>void</code>
  40 and exists only for semantical reasons - thus we can differentiate between
  41 <code>void *</code> (arbitrary data) and <code>TALLOC_CTX *</code> (talloc
  42 context).
  43
  44 @subsection metadata Context meta data
  45
  46 Every talloc context carries several pieces of internal information along with
  47 the allocated memory:
  48
  49   - name - which is used in reports of context hierarchy and to simulate
  50     a dynamic type system,
  51   - size of the requested memory in bytes - this can be used to determine
  52     the number of elements in arrays,
  53   - attached destructor - which is executed just before the memory block is
  54     about to be freed,
  55   - references to the context
  56   - children and parent contexts - create the hierarchical view on the
  57     memory.
  58
  59 @section context-hierarchy Hierarchy of talloc context
  60
  61 Every talloc context contains information about its parent and children. Talloc
  62 uses this information to create a hierarchical model of memory or to be more
  63 precise, it creates an n-ary tree where each node represents a single talloc
  64 context. The root node of the tree is referred to as a top level context - a
  65 context without any parent.
  66
  67 This approach has several advantages:
  68
  69   - as a consequence of freeing a talloc context, all of its children
  70     will be properly deallocated as well,
  71   - the parent of a context can be changed at any time, which
  72     results in moving the whole subtree under another node,
  73   - it creates a more natural way of managing data structures.
  74
  75 @subsection Example
  76
  77 We have a structure that stores basic information about a user - his/her name,
  78 identification number and groups he/she is a member of:
  79
  80 @code
  81 struct user {
  82   uid_t uid;
  83   char *username;
  84   size_t num_groups;
  85   char **groups;
  86 };
  87 @endcode
  88
  89 We will allocate this structure using talloc. The result will be the following
  90 context tree:
  91
  92 @image html context_tree.png
  93
  94 @code
  95 /* create new top level context */
  96 struct user *user = talloc(NULL, struct user);
  97
  98 user->uid = 1000;
  99 user->num_groups = N;
 100
 101 /* make user the parent of following contexts */
 102 user->username = talloc_strdup(user, "Test user");
 103 user->groups = talloc_array(user, char*, user->num_groups);
 104
 105 for (i = 0; i < user->num_groups; i++) {
 106   /* make user->groups the parent of following context */
 107   user->groups[i] = talloc_asprintf(user->groups,
 108                                     "Test group %d", i);
 109 }
 110 @endcode
 111
 112 This way, we have gained a lot of additional capabilities, one of which is
 113 very simple deallocation of the structure and all of its elements.
 114
 115 With the C standard library we need first to iterate over the array of groups
 116 and free every element separately. Then we must deallocate the array that stores
 117 them. Next we deallocate the username and as the last step free the structure
 118 itself. But with talloc, the only operation we need to execute is freeing the
 119 structure context. Its descendants will be freed automatically.
 120
 121 @code
 122 talloc_free(user);
 123 @endcode
 124
 125 @section keep-hierarchy Always keep the hieararchy steady!
 126
 127 The talloc is a hierarchy memory allocator. The hierarchy nature is what makes
 128 the programming more error proof. It makes the memory easier to manage and to
 129 free.  Therefore, the first thing we should have on our mind is: <strong>always
 130 project our data structures into the talloc context hierarchy</strong>.
 131
 132 That means if we have a structure, we should always use it as a parent context
 133 for its elements. This way we will not encounter any troubles when freeing this
 134 structure or when changing its parent. The same rule applies for arrays.
 135
 136 @section creating-context Creating a talloc context
 137
 138 Here are the most important functions that create a new talloc context.
 139
 140 @subsection type-safe Type-safe functions
 141
 142 It allocates the size that is necessary for the given type and returns a new,
 143 properly-casted pointer. This is the preferred way to create a new context as
 144 we can rely on the compiler to detect type mismatches.
 145
 146 The name of the context is automatically set to the name of the data type which
 147 is used to simulate a dynamic type system.
 148
 149 @code
 150 struct user *user = talloc(ctx, struct user);
 151
 152 /* initialize to default values */
 153 user->uid = 0;
 154 user->name = NULL;
 155 user->num_groups = 0;
 156 user->groups = NULL;
 157
 158 /* or we can achieve the same result with */
 159 struct user *user_zero = talloc_zero(ctx, struct user);
 160 @endcode
 161
 162 @subsection zero-length Zero-length contexts
 163
 164 The zero-length context is basically a context without any special semantical
 165 meaning. We can use it the same way as any other context. The only difference
 166 is that it consists only of the meta data about the context. Therefore, it is
 167 strictly of type <code>TALLOC_CTX*</code>. It is often used in cases where we
 168 want to aggregate several data structures under one parent (zero-length)
 169 context, such as a temporary context to contain memory needed within a single
 170 function that is not interesting to the caller. Allocating on a zero-length
 171 temporary context will make clean-up of the function simpler.
 172
 173 @code
 174 TALLOC_CTX *tmp_ctx = NULL;
 175 struct foo *foo = NULL;
 176 struct bar *bar = NULL;
 177
 178 /* new zero-length top level context */
 179 tmp_ctx = talloc_new(NULL);
 180 if (tmp_ctx == NULL) {
 181   return ENOMEM;
 182 }
 183
 184 foo = talloc(tmp_ctx, struct foo);
 185 bar = talloc(tmp_ctx, struct bar);
 186
 187 /* free everything at once */
 188 talloc_free(tmp_ctx);
 189 @endcode
 190
 191 @subsection context-see-also See also
 192
 193 - talloc_size()
 194 - talloc_named()
 195 - @ref talloc_array
 196 - @ref talloc_string
 197
 198 */