r3478: split out some more pieces of includes.h
[bbaumbach/samba-autobuild/.git] / talloc_guide.txt
index b61e08e708012fd53ad62b8a68eaf12604f07160..a794cdffbe51cae1cf09a3773e553132cd627654 100644 (file)
@@ -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
@@ -102,10 +101,12 @@ condition is if the pointer had a destructor attached to it and the
 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.
+If this pointer has an additional parent when talloc_free() is called
+then the memory is not actually released, but instead the most
+recently established parent is destroyed. See talloc_reference() for
+details on establishing additional parents.
+
+For more control on which parent is removed, see talloc_unlink()
 
 talloc_free() operates recursively on its children.
 
@@ -113,8 +114,8 @@ talloc_free() operates recursively on its children.
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 void *talloc_reference(const void *context, const void *ptr);
 
-The talloc_reference() function returns an additional reference to
-"ptr", and makes this additional reference a child of "context".
+The talloc_reference() function makes "context" an additional parent
+of "ptr".
 
 The return value of talloc_reference() is always the original pointer
 "ptr", unless talloc ran out of memory in creating the reference in
@@ -124,34 +125,30 @@ around 48 bytes of memory on intel x86 platforms).
 After creating a reference you can free it in one of the following
 ways:
 
-  - you can talloc_free() a parent of the original pointer. That will
-    destroy the reference and make the pointer a child of the
-    "context" argument from the most recently called
-    talloc_reference() on the pointer.
+  - you can talloc_free() any parent of the original pointer. That
+    will reduce the number of parents of this pointer by 1, and will
+    cause this pointer to be freed if it runs out of parents.
 
   - you can talloc_free() the pointer itself. That will destroy the
-    most recently established reference to the pointer and leave the
+    most recently established parent to the pointer and leave the
     pointer as a child of its current parent.
 
-  - you can talloc_free() the context where you placed the
-    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.
 
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
@@ -203,6 +200,14 @@ The main use for names on pointer is for "talloc reports". See
 talloc_report() and talloc_report_full() for details. Also see
 talloc_enable_leak_report() and talloc_enable_leak_report_full().
 
+The talloc_set_name() function allocates memory as a child of the
+pointer. It is logically equivalent to:
+  talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
+
+Note that multiple calls to talloc_set_name() will allocate more
+memory without releasing the name. All of the memory is released when
+the ptr is freed using talloc_free().
+
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 void talloc_set_name_const(const void *ptr, const char *name);
@@ -211,6 +216,11 @@ The function talloc_set_name_const() is just like talloc_set_name(),
 but it takes a string constant, and is much faster. It is extensively
 used by the "auto naming" macros, such as talloc_p().
 
+This function does not allocate any memory. It just copies the
+supplied pointer into the internal representation of the talloc
+ptr. This means you must not pass a name pointer to memory that will
+disappear before the ptr is freed with talloc_free().
+
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 void *talloc_named(const void *context, size_t size, const char *fmt, ...);
@@ -261,7 +271,7 @@ is ignored.
 
 talloc_realloc() returns the new pointer, or NULL on failure. The call
 will fail either due to a lack of memory, or because the pointer has
-an reference (see talloc_reference()).
+more than one parent (see talloc_reference()).
 
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
@@ -406,6 +416,9 @@ The talloc_strdup() function is equivalent to:
   ptr = talloc(ctx, strlen(p)+1);
   if (ptr) memcpy(ptr, p, strlen(p)+1);
 
+This functions sets the name of the new pointer to the passed
+string. This is equivalent to:
+   talloc_set_name_const(ptr, ptr)
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 char *talloc_strndup(const void *t, const char *p, size_t n);
@@ -413,6 +426,10 @@ char *talloc_strndup(const void *t, const char *p, size_t n);
 The talloc_strndup() function is the talloc equivalent of the C
 library function strndup()
 
+This functions sets the name of the new pointer to the passed
+string. This is equivalent to:
+   talloc_set_name_const(ptr, ptr)
+
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap);
@@ -427,6 +444,10 @@ char *talloc_asprintf(const void *t, const char *fmt, ...);
 The talloc_asprintf() function is the talloc equivalent of the C
 library function asprintf()
 
+This functions sets the name of the new pointer to the passed
+string. This is equivalent to:
+   talloc_set_name_const(ptr, ptr)
+
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 char *talloc_asprintf_append(char *s, const char *fmt, ...);
@@ -456,3 +477,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.
+