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
+-----------
+
+All the additional features of talloc() over malloc() do come at a
+price. We have a simple performance test in Samba4 that measures
+talloc() versus malloc() performance, and it seems that talloc() is
+about 10% slower than malloc() on my x86 Debian Linux box. For Samba,
+the great reduction in code complexity that we get by using talloc
+makes this worthwhile, especially as the total overhead of
+talloc/malloc in Samba is already quite small.
talloc API
level context is created.
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+void *talloc_p(const void *context, type);
+
+The talloc_p() macro is the equivalent of
+
+ (type *)talloc(ctx, sizeof(type))
+
+You should use it in preference to talloc() whenever possible, as it
+provides additional type safety. It also automatically calls the
+talloc_set_name_const() function with the name being a string holding
+the name of the type.
+
+
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
int talloc_free(void *ptr);
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 and the memory becomes a child of the
-referrer. 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.
ways:
- you can talloc_free() a parent of the original pointer. That will
- destroy the reference and make the pointer a child of "context".
+ 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() the pointer itself. That will destroy the
- reference and make the pointer a child of "context".
+ most recently established reference 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()
+
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+int talloc_unlink(const void *context, const void *ptr);
+
+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 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_unlink(), but
+sometimes it is useful to have the additional control on which parent
+is removed.
+
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
The talloc_total_size() function returns the total size in bytes used
by this pointer and all child pointers. Mostly useful for debugging.
+Passing NULL is allowed, but it will only give a meaningful result if
+talloc_enable_leak_report() or talloc_enable_leak_report_full() has
+been called.
+
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+off_t talloc_total_blocks(const void *ptr);
+
+The talloc_total_blocks() function returns the total memory block
+count used by this pointer and all child pointers. Mostly useful for
+debugging.
+
+Passing NULL is allowed, but it will only give a meaningful result if
+talloc_enable_leak_report() or talloc_enable_leak_report_full() has
+been called.
+
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
void talloc_report(const void *ptr, FILE *f);
ptr, showing the total memory and number of blocks used by that child.
You can pass NULL for the pointer, in which case a report is printed
-for the top level memory context.
+for the top level memory context, but only if
+talloc_enable_leak_report() or talloc_enable_leak_report_full() has
+been called.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
pointer that is referenced.
You can pass NULL for the pointer, in which case a report is printed
-for the top level memory context.
+for the top level memory context, but only if
+talloc_enable_leak_report() or talloc_enable_leak_report_full() has
+been called.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
exits. In Samba4 this is enabled by using the --leak-report command
line option.
+For it to be useful, this function must be called before any other
+talloc function as it establishes a "null context" that acts as the
+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);
program exits. In Samba4 this is enabled by using the
--leak-report-full command line option.
+For it to be useful, this function must be called before any other
+talloc function as it establishes a "null context" that acts as the
+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);
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.
+
git.samba.org / sfrench / samba-autobuild / .git / blobdiff