r2792: got rid of talloc_ldb_alloc() and instead created talloc_realloc_fn(),

[bbaumbach/samba-autobuild/.git] / talloc_guide.txt

diff --git a/talloc_guide.txt b/talloc_guide.txt
index 745426730c629c133b0926b422411fc1d8f6eb5a..484b4c8228582ebf7d034636bde180312ff7f16a 100644 (file)
--- a/talloc_guide.txt
+++ b/talloc_guide.txt
@@ -33,10 +33,9 @@ n-ary tree, where you can free any part of the tree with
 talloc_free().
 
 If you find this confusing, then I suggest you run the LOCAL-TALLOC
-smbtorture test with the --leak-report-full option to watch talloc in
-action. You may also like to add your own tests to
-source/torture/local/talloc.c to clarify how some particular situation
-is handled.
+smbtorture test to watch talloc in action. You may also like to add
+your own tests to source/torture/local/talloc.c to clarify how some
+particular situation is handled.
 
 
 Performance
@@ -103,9 +102,11 @@ destructor returned -1. See talloc_set_destructor() for details on
 destructors.
 
 If this pointer has an additional reference when talloc_free() is
-called then the memory is not actually released, but instead the
-reference is destroyed. See talloc_reference() for details on
-establishing additional references.
+called then the memory is not actually released, but instead the most
+recently established reference is destroyed. See talloc_reference()
+for details on establishing additional references.
+
+For more control on which parent is removed, see talloc_unlink()
 
 talloc_free() operates recursively on its children.
 
@@ -137,21 +138,22 @@ ways:
     reference. That will destroy the reference, and leave the pointer
     where it is.
 
+For more control on which parent to remove, see talloc_unlink()
+
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-void *talloc_unreference(const void *context, const void *ptr);
+int talloc_unlink(const void *context, const void *ptr);
 
-The talloc_unreference() function removes a reference added by
-talloc_reference(). It must be called with exactly the same arguments
-as talloc_reference().
+The talloc_unlink() function removes a specific parent from ptr. The
+context passed must either be a context used in talloc_reference()
+with this pointer, or must be a direct parent of ptr. 
 
-Note that if the reference has already been removed using
-talloc_free() then this function will fail and will return NULL.
+Note that if the parent has already been removed using talloc_free()
+then this function will fail and will return -1.
 
-Usually you can just use talloc_free() instead of
-talloc_unreference(), but sometimes it is useful to have the
-additional control on who becomes the parent of the pointer given by
-talloc_unreference().
+Usually you can just use talloc_free() instead of talloc_unlink(), but
+sometimes it is useful to have the additional control on which parent
+is removed.
 
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
@@ -343,6 +345,17 @@ top of the tree. If you don't call this function first then passing
 NULL to talloc_report() or talloc_report_full() won't give you the
 full tree printout.
 
+Here is a typical talloc report:
+
+talloc report on 'null_context' (total 267 bytes in 15 blocks)
+        libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
+        libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
+        iconv(UTF8,CP850)              contains     42 bytes in   2 blocks
+        libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
+        iconv(CP850,UTF8)              contains     42 bytes in   2 blocks
+        iconv(UTF8,UTF-16LE)           contains     45 bytes in   2 blocks
+        iconv(UTF-16LE,UTF8)           contains     45 bytes in   2 blocks
+
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 void talloc_enable_leak_report_full(void);
@@ -357,6 +370,17 @@ top of the tree. If you don't call this function first then passing
 NULL to talloc_report() or talloc_report_full() won't give you the
 full tree printout.
 
+Here is a typical full report:
+
+full talloc report on 'root' (total 18 bytes in 8 blocks)
+    p1                             contains     18 bytes in   7 blocks (ref 0)
+        r1                             contains     13 bytes in   2 blocks (ref 0)
+            reference to: p2
+        p2                             contains      1 bytes in   1 blocks (ref 1)
+        x3                             contains      1 bytes in   1 blocks (ref 0)
+        x2                             contains      1 bytes in   1 blocks (ref 0)
+        x1                             contains      1 bytes in   1 blocks (ref 0)
+
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 void *talloc_zero(const void *ctx, size_t size);
@@ -434,3 +458,13 @@ The talloc_realloc_p() macro is equivalent to:
 except that it provides integer overflow protection for the multiply,
 returning NULL if the multiply overflows.
 
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size);
+
+This is a non-macro version of talloc_realloc(), which is useful 
+as libraries sometimes want a ralloc function pointer. A realloc()
+implementation encapsulates the functionality of malloc(), free() and
+realloc() in one call, which is why it is useful to be able to pass
+around a single function pointer.
+