libtalloc_stealing(3) talloc libtalloc_stealing(3)NAME
libtalloc_stealing - Chapter 2: Stealing a context
Stealing a context
Talloc has the ability to change the parent of a talloc context to another one. This operation is commonly referred to as stealing and it
is one of the most important actions performed with talloc contexts.
Stealing a context is necessary if we want the pointer to outlive the context it is created on. This has many possible use cases, for
instance stealing a result of a database search to an in-memory cache context, changing the parent of a field of a generic structure to a
more specific one or vice-versa. The most common scenario, at least in Samba, is to steal output data from a function-specific context to
the output context given as an argument of that function.
struct foo {
char *a1;
char *a2;
char *a3;
};
struct bar {
char *wurst;
struct foo *foo;
};
struct foo *foo = talloc_zero(ctx, struct foo);
foo->a1 = talloc_strdup(foo, "a1");
foo->a2 = talloc_strdup(foo, "a2");
foo->a3 = talloc_strdup(foo, "a3");
struct bar *bar = talloc_zero(NULL, struct bar);
/* change parent of foo from ctx to bar */
bar->foo = talloc_steal(bar, foo);
/* or do the same but assign foo = NULL */
bar->foo = talloc_move(bar, &foo);
The talloc_move() function is similar to the talloc_steal() function but additionally sets the source pointer to NULL.
In general, the source pointer itself is not changed (it only replaces the parent in the meta data). But the common usage is that the
result is assigned to another variable, thus further accessing the pointer from the original variable should be avoided unless it is
necessary. In this case talloc_move() is the preferred way of stealing a context. Additionally sets the source pointer to NULL,
thus.protects the pointer from being accidentally freed and accessed using the old variable after its parent has been changed.
Version 2.0 Tue Jun 17 2014 libtalloc_stealing(3)
Check Out this Related Man Page
libtalloc_context(3) talloc libtalloc_context(3)NAME
libtalloc_context - Chapter 1: Talloc context
Talloc context
The talloc context is the most important part of this library and is responsible for every single feature of this memory allocator. It is a
logical unit which represents a memory space managed by talloc.
From the programmer's point of view, the talloc context is completely equivalent to a pointer that would be returned by the memory routines
from the C standard library. This means that every context that is returned from the talloc library can be used directly in functions that
do not use talloc internally. For example we can do the following:
char *str1 = strdup("I am NOT a talloc context");
char *str2 = talloc_strdup(NULL, "I AM a talloc context");
printf("%d0, strcmp(str1, str2) == 0);
free(str1);
talloc_free(str2); /* we can not use free() on str2 */
This is possible because the context is internally handled as a special fixed-length structure called talloc chunk. Each chunk stores
context metadata followed by the memory space requested by the programmer. When a talloc function returns a context (pointer), it will in
fact return a pointer to the user space portion of the talloc chunk. If we to manipulate this context using talloc functions, the talloc
library transforms the user-space pointer back to the starting address of the chunk. This is also the reason why we were unable to use
free(str2) in the previous example - because str2 does not point at the beginning of the allocated block of memory. This is illustrated on
the next image:
The type TALLOC_CTX is defined in talloc.h to identify a talloc context in function parameters. However, this type is just an alias for
void and exists only for semantical reasons - thus we can differentiate between void * (arbitrary data) and TALLOC_CTX * (talloc context).
Context meta data
Every talloc context carries several pieces of internal information along with the allocated memory:
o name - which is used in reports of context hierarchy and to simulate a dynamic type system,
o size of the requested memory in bytes - this can be used to determine the number of elements in arrays,
o attached destructor - which is executed just before the memory block is about to be freed,
o references to the context
o children and parent contexts - create the hierarchical view on the memory.
Hierarchy of talloc context
Every talloc context contains information about its parent and children. Talloc uses this information to create a hierarchical model of
memory or to be more precise, it creates an n-ary tree where each node represents a single talloc context. The root node of the tree is
referred to as a top level context - a context without any parent.
This approach has several advantages:
o as a consequence of freeing a talloc context, all of its children will be properly deallocated as well,
o the parent of a context can be changed at any time, which results in moving the whole subtree under another node,
o it creates a more natural way of managing data structures.
Example
We have a structure that stores basic information about a user - his/her name, identification number and groups he/she is a member of:
struct user {
uid_t uid;
char *username;
size_t num_groups;
char **groups;
};
We will allocate this structure using talloc. The result will be the following context tree:
/* create new top level context */
struct user *user = talloc(NULL, struct user);
user->uid = 1000;
user->num_groups = N;
/* make user the parent of following contexts */
user->username = talloc_strdup(user, "Test user");
user->groups = talloc_array(user, char*, user->num_groups);
for (i = 0; i < user->num_groups; i++) {
/* make user->groups the parent of following context */
user->groups[i] = talloc_asprintf(user->groups,
"Test group %d", i);
}
This way, we have gained a lot of additional capabilities, one of which is very simple deallocation of the structure and all of its
elements.
With the C standard library we need first to iterate over the array of groups and free every element separately. Then we must deallocate
the array that stores them. Next we deallocate the username and as the last step free the structure itself. But with talloc, the only
operation we need to execute is freeing the structure context. Its descendants will be freed automatically.
talloc_free(user);
Always keep the hieararchy steady!
The talloc is a hierarchy memory allocator. The hierarchy nature is what makes the programming more error proof. It makes the memory easier
to manage and to free. Therefore, the first thing we should have on our mind is: always project our data structures into the talloc context
hierarchy.
That means if we have a structure, we should always use it as a parent context for its elements. This way we will not encounter any
troubles when freeing this structure or when changing its parent. The same rule applies for arrays.
Creating a talloc context
Here are the most important functions that create a new talloc context.
Type-safe functions
It allocates the size that is necessary for the given type and returns a new, properly-casted pointer. This is the preferred way to create
a new context as we can rely on the compiler to detect type mismatches.
The name of the context is automatically set to the name of the data type which is used to simulate a dynamic type system.
struct user *user = talloc(ctx, struct user);
/* initialize to default values */
user->uid = 0;
user->name = NULL;
user->num_groups = 0;
user->groups = NULL;
/* or we can achieve the same result with */
struct user *user_zero = talloc_zero(ctx, struct user);
Zero-length contexts
The zero-length context is basically a context without any special semantical meaning. We can use it the same way as any other context. The
only difference is that it consists only of the meta data about the context. Therefore, it is strictly of type TALLOC_CTX*. It is often
used in cases where we want to aggregate several data structures under one parent (zero-length) context, such as a temporary context to
contain memory needed within a single function that is not interesting to the caller. Allocating on a zero-length temporary context will
make clean-up of the function simpler.
TALLOC_CTX *tmp_ctx = NULL;
struct foo *foo = NULL;
struct bar *bar = NULL;
/* new zero-length top level context */
tmp_ctx = talloc_new(NULL);
if (tmp_ctx == NULL) {
return ENOMEM;
}
foo = talloc(tmp_ctx, struct foo);
bar = talloc(tmp_ctx, struct bar);
/* free everything at once */
talloc_free(tmp_ctx);
See also
o talloc_size()
o talloc_named()
o The talloc array functions
o The talloc string functions.
Version 2.0 Tue Jun 17 2014 libtalloc_context(3)