diff options
author | Pavel Březina <pbrezina@redhat.com> | 2012-05-06 14:34:48 +0200 |
---|---|---|
committer | Andreas Schneider <asn@samba.org> | 2012-05-07 19:20:29 +0200 |
commit | d99b7d0220d8bd694c0d997622a7a87eb09c5570 (patch) | |
tree | 7d65ff8d83faef7e7d0464d8408db8ec2ac4a719 /lib/talloc/doc/tutorial_stealing.dox | |
parent | 890485bd17142ac9bbaf71c24d3d3ec1fa4a6724 (diff) | |
download | samba-d99b7d0220d8bd694c0d997622a7a87eb09c5570.tar.gz samba-d99b7d0220d8bd694c0d997622a7a87eb09c5570.tar.bz2 samba-d99b7d0220d8bd694c0d997622a7a87eb09c5570.zip |
doc: Add talloc tutorial.
Signed-off-by: Andreas Schneider <asn@samba.org>
Diffstat (limited to 'lib/talloc/doc/tutorial_stealing.dox')
-rw-r--r-- | lib/talloc/doc/tutorial_stealing.dox | 40 |
1 files changed, 40 insertions, 0 deletions
diff --git a/lib/talloc/doc/tutorial_stealing.dox b/lib/talloc/doc/tutorial_stealing.dox new file mode 100644 index 0000000000..9ac5cbd3f9 --- /dev/null +++ b/lib/talloc/doc/tutorial_stealing.dox @@ -0,0 +1,40 @@ +/** +@page libtalloc_stealing Chapter 2: Stealing a context +@section stealing 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 SSSD, is to steal output data from a function-specific +context to the output context given as an argument of that function. + +@code +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); +@endcode + +In general, the 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 as it protects the +pointer from being accidentally freed and accessed using the old variable after +its parent has been changed. + +@image html stealing.png + +*/
\ No newline at end of file |