1libtalloc_bestpractices(3)          talloc          libtalloc_bestpractices(3)
2
3
4

NAME

6       libtalloc_bestpractices - Chapter 7: Best practises The following
7       sections contain several best practices and good manners that were
8       found by the Samba and SSSD developers over the years.
9
10       These will help you to write code which is better, easier to debug and
11       with as few (hopefully none) memory leaks as possible.
12

Keep the context hierarchy steady

14       The talloc is a hierarchy memory allocator. The hierarchy nature is
15       what makes the programming more error proof. It makes the memory easier
16       to manage and to free. Therefore, the first thing we should have on our
17       mind is: always project your data structures into the talloc context
18       hierarchy.
19
20       That means if we have a structure, we should always use it as a parent
21       context for its elements. This way we will not encounter any troubles
22       when freeing the structure or when changing its parent. The same rule
23       applies for arrays.
24
25       For example, the structure user from section Hierarchy of talloc
26       context should be created with the context hierarchy illustrated on the
27       next image.
28

Every function should use its own context

30       It is a good practice to create a temporary talloc context at the
31       function beginning and free the context just before the return
32       statement. All the data must be allocated on this context or on its
33       children. This ensures that no memory leaks are created as long as we
34       do not forget to free the temporary context.
35
36       This pattern applies to both situations - when a function does not
37       return any dynamically allocated value and when it does. However, it
38       needs a little extension for the latter case.
39
40   Functions that do not return any dynamically allocated
41       value
42
43       If the function does not return any value created on the heap, we will
44       just obey the aforementioned pattern.
45
46       int bar()
47       {
48         int ret;
49         TALLOC_CTX *tmp_ctx = talloc_new(NULL);
50         if (tmp_ctx == NULL) {
51           ret = ENOMEM;
52           goto done;
53         }
54         /* allocate data on tmp_ctx or on its descendants */
55         ret = EOK;
56       done:
57         talloc_free(tmp_ctx);
58         return ret;
59       }
60
61   Functions returning dynamically allocated values
62       If our function returns any dynamically allocated data, its first
63       parameter should always be the destination talloc context. This context
64       serves as a parent for the output values. But again, we will create the
65       output values as the descendants of the temporary context. If
66       everything goes well, we will change the parent of the output values
67       from the temporary to the destination talloc context.
68
69       This pattern ensures that if an error occurs (e.g. I/O error or
70       insufficient amount of the memory), all allocated data is freed and no
71       garbage appears on the destination context.
72
73       int struct_foo_init(TALLOC_CTX *mem_ctx, struct foo **_foo)
74       {
75         int ret;
76         struct foo *foo = NULL;
77         TALLOC_CTX *tmp_ctx = talloc_new(NULL);
78         if (tmp_ctx == NULL) {
79           ret = ENOMEM;
80           goto done;
81         }
82         foo = talloc_zero(tmp_ctx, struct foo);
83         /* ... */
84         *_foo = talloc_steal(mem_ctx, foo);
85         ret = EOK;
86       done:
87         talloc_free(tmp_ctx);
88         return ret;
89       }
90

Allocate temporary contexts on NULL

92       As it can be seen on the previous listing, instead of allocating the
93       temporary context directly on mem_ctx, we created a new top level
94       context using NULL as the parameter for talloc_new() function. Take a
95       look at the following example:
96
97       char *create_user_filter(TALLOC_CTX *mem_ctx,
98                                uid_t uid, const char *username)
99       {
100         char *filter = NULL;
101         char *sanitized_username = NULL;
102         /* tmp_ctx is a child of mem_ctx */
103         TALLOC_CTX *tmp_ctx = talloc_new(mem_ctx);
104         if (tmp_ctx == NULL) {
105           return NULL;
106         }
107
108         sanitized_username = sanitize_string(tmp_ctx, username);
109         if (sanitized_username == NULL) {
110           talloc_free(tmp_ctx);
111           return NULL;
112         }
113
114         filter = talloc_aprintf(tmp_ctx,"(|(uid=%llu)(uname=%s))",
115                                 uid, sanitized_username);
116         if (filter == NULL) {
117           return NULL; /* tmp_ctx is not freed */ (*@el{lst:tmp-ctx-3:leak}@*)
118         }
119
120         /* filter becomes a child of mem_ctx */
121         filter = talloc_steal(mem_ctx, filter);
122         talloc_free(tmp_ctx);
123         return filter;
124       }
125
126       We forgot to free tmp_ctx before the return statement in the filter ==
127       NULL condition. However, it is created as a child of mem_ctx context
128       and as such it will be freed as soon as the mem_ctx is freed.
129       Therefore, no detectable memory leak is created.
130
131       On the other hand, we do not have any way to access the allocated data
132       and for all we know mem_ctx may exist for the lifetime of our
133       application. For these reasons this should be considered as a memory
134       leak. How can we detect if it is unreferenced but still attached to its
135       parent context? The only way is to notice the mistake in the source
136       code.
137
138       But if we create the temporary context as a top level context, it will
139       not be freed and memory diagnostic tools (e.g. valgrind) are able to do
140       their job.
141

Temporary contexts and the talloc pool

143       If we want to take the advantage of the talloc pool but also keep to
144       the pattern introduced in the previous section, we are unable to do it
145       directly. The best thing to do is to create a conditional build where
146       we can decide how do we want to create the temporary context. For
147       example, we can create the following macros:
148
149       #ifdef USE_POOL_CONTEXT
150         #define CREATE_POOL_CTX(ctx, size) talloc_pool(ctx, size)
151         #define CREATE_TMP_CTX(ctx)        talloc_new(ctx)
152       #else
153         #define CREATE_POOL_CTX(ctx, size) talloc_new(ctx)
154         #define CREATE_TMP_CTX(ctx)        talloc_new(NULL)
155       #endif
156
157       Now if our application is under development, we will build it with
158       macro USE_POOL_CONTEXT undefined. This way, we can use memory
159       diagnostic utilities to detect memory leaks.
160
161       The release version will be compiled with the macro defined. This will
162       enable pool contexts and therefore reduce the malloc() calls, which
163       will end up in a little bit faster processing.
164
165       int struct_foo_init(TALLOC_CTX *mem_ctx, struct foo **_foo)
166       {
167         int ret;
168         struct foo *foo = NULL;
169         TALLOC_CTX *tmp_ctx = CREATE_TMP_CTX(mem_ctx);
170         /* ... */
171       }
172
173       errno_t handle_request(TALLOC_CTX mem_ctx)
174       {
175         int ret;
176         struct foo *foo = NULL;
177         TALLOC_CTX *pool_ctx = CREATE_POOL_CTX(NULL, 1024);
178         ret = struct_foo_init(mem_ctx, &foo);
179         /* ... */
180       }
181
182Version 2.0                     Tue Jan 26 2021     libtalloc_bestpractices(3)
Impressum