sin/samba-mirror
1
0
Fork 0
mirror of https://github.com/samba-team/samba.git synced 2024-12-23 17:34:34 +03:00
Code

updated talloc guide for recent API changes

Browse Source
This commit is contained in:
Andrew Tridgell 2009-08-24 12:34:53 +10:00
parent 39cd5bbb33
commit a0e2041836
1 changed files with 54 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
lib/talloc/talloc_guide.txt
View File

@ -4,10 +4,10 @@ Using talloc in Samba4
.. contents::
Andrew Tridgell
September 2004
August 2009
The most current version of this document is available at
http://samba.org/ftp/unpacked/samba4/source/lib/talloc/talloc_guide.txt
http://samba.org/ftp/unpacked/talloc/talloc_guide.txt
If you are used to the "old" talloc from Samba3 before 3.0.20 then please read
this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the
@ -131,6 +131,22 @@ For more control on which parent is removed, see talloc_unlink()
talloc_free() operates recursively on its children.
As a special case, talloc_free() is refused on pointers that have more
than one parent, as talloc would have no way of knowing which parent
should be removed. To free a pointer that has more than one parent
please use talloc_unlink().
To help you find problems in your code caused by this behaviour, if
you do try and free a pointer with more than one parent then the
talloc logging function will be called to give output like this:
ERROR: talloc_free with references at some_dir/source/foo.c:123
reference at some_dir/source/other.c:325
reference at some_dir/source/third.c:121
Please see the documentation for talloc_set_log_fn() and
talloc_set_log_stderr() for more information on talloc logging
functions.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
int talloc_free_children(void *ptr);
@ -349,6 +365,42 @@ as to your sanity or the safety of your data if you do this.
talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
Note that if you try and call talloc_steal() on a pointer that has
more than one parent then the result is ambiguous. Talloc will choose
to remove the parent that is currently indicated by talloc_parent()
and replace it with the chosen parent. You will also get a message
like this via the talloc logging functions:
WARNING: talloc_steal with references at some_dir/source/foo.c:123
reference at some_dir/source/other.c:325
reference at some_dir/source/third.c:121
To unambiguously change the parent of a pointer please see the
function talloc_reparent(). See the talloc_set_log_fn() documentation
for more information on talloc logging.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
void *talloc_reparent(const void *old_parent, const void *new_parent, const void *ptr);
The talloc_reparent() function changes the parent context of a talloc
pointer. It is typically used when the context that the pointer is
currently a child of is going to be freed and you wish to keep the
memory for a longer time.
The talloc_reparent() function returns the pointer that you pass it. It
does not have any failure modes.
The difference between talloc_reparent() and talloc_steal() is that
talloc_reparent() can specify which parent you wish to change. This is
useful when a pointer has multiple parents via references.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
void *talloc_parent(const void *ptr);
The talloc_parent() function returns the current talloc parent. This
is usually the pointer under which this memory was originally created,
but it may have changed due to a talloc_steal() or talloc_reparent()
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
size_t talloc_total_size(const void *ptr);