From a0e20418360cbbb0ddaff5f71675300b3b3db72a Mon Sep 17 00:00:00 2001 From: Andrew Tridgell Date: Mon, 24 Aug 2009 12:34:53 +1000 Subject: [PATCH] updated talloc guide for recent API changes --- lib/talloc/talloc_guide.txt | 56 +++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/lib/talloc/talloc_guide.txt b/lib/talloc/talloc_guide.txt index 3201fe6f0f0..7890f9f265c 100644 --- a/lib/talloc/talloc_guide.txt +++ b/lib/talloc/talloc_guide.txt @@ -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);