lib/talloc/doc/tutorial_stealing.dox

   1 /**
   2 @page libtalloc_stealing Chapter 2: Stealing a context
   3
   4 @section stealing Stealing a context
   5
   6 Talloc has the ability to change the parent of a talloc context to another
   7 one. This operation is commonly referred to as stealing and it is one of
   8 the most important actions performed with talloc contexts.
   9
  10 Stealing a context is necessary if we want the pointer to outlive the context it
  11 is created on. This has many possible use cases, for instance stealing a result
  12 of a database search to an in-memory cache context, changing the parent of a
  13 field of a generic structure to a more specific one or vice-versa. The most
  14 common scenario, at least in Samba, is to steal output data from a function-specific
  15 context to the output context given as an argument of that function.
  16
  17 @code
  18 struct foo {
  19     char *a1;
  20     char *a2;
  21     char *a3;
  22 };
  23
  24 struct bar {
  25     char *wurst;
  26     struct foo *foo;
  27 };
  28
  29 struct foo *foo = talloc_zero(ctx, struct foo);
  30 foo->a1 = talloc_strdup(foo, "a1");
  31 foo->a2 = talloc_strdup(foo, "a2");
  32 foo->a3 = talloc_strdup(foo, "a3");
  33
  34 struct bar *bar = talloc_zero(NULL, struct bar);
  35 /* change parent of foo from ctx to bar */
  36 bar->foo = talloc_steal(bar, foo);
  37
  38 /* or do the same but assign foo = NULL */
  39 bar->foo = talloc_move(bar, &foo);
  40 @endcode
  41
  42 The talloc_move() function is similar to the talloc_steal() function but
  43 additionally sets the source pointer to NULL.
  44
  45 In general, the source pointer itself is not changed (it only replaces the
  46 parent in the meta data). But the common usage is that the result is
  47 assigned to another variable, thus further accessing the pointer from the
  48 original variable should be avoided unless it is necessary. In this case
  49 talloc_move() is the preferred way of stealing a context. Additionally sets the
  50 source pointer to NULL, thus.protects the pointer from being accidentally freed
  51 and accessed using the old variable after its parent has been changed.
  52
  53 @image html stealing.png
  54
  55 */