sin/samba-mirror
1
0
Fork 0
mirror of https://github.com/samba-team/samba.git synced 2025-02-02 09:47:23 +03:00
Code

Move the talloc details to the mainpage.

Browse Source 
Signed-off-by: Andrew Tridgell <tridge@samba.org>
This commit is contained in:
Andreas Schneider 2010-02-08 00:40:07 +01:00 committed by Andrew Tridgell
parent 52c0cd38fa
commit da0e396deb
2 changed files with 69 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
lib/talloc/doc/mainpage.dox
View File

@ -33,4 +33,73 @@
*
* rsync -Pavz samba.org::ftp/unpacked/standalone_projects/lib/talloc .
*
* @section talloc_preample Preamble
*
* talloc is a hierarchical, reference counted memory pool system with
* destructors.
*
* Perhaps the biggest difference from other memory pool systems is that there
* is no distinction between a "talloc context" and a "talloc pointer". Any
* pointer returned from talloc() is itself a valid talloc context. This means
* you can do this:
*
* @code
* struct foo *X = talloc(mem_ctx, struct foo);
* X->name = talloc_strdup(X, "foo");
* @endcode
*
* The pointer X->name would be a "child" of the talloc context "X" which is
* itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is all
* destroyed, whereas if you do talloc_free(X) then just X and X->name are
* destroyed, and if you do talloc_free(X->name) then just the name element of
* X is destroyed.
*
* If you think about this, then what this effectively gives you is an n-ary
* tree, where you can free any part of the tree with talloc_free().
*
* If you find this confusing, then run the testsuite to watch talloc in
* action. You may also like to add your own tests to testsuite.c to clarify
* how some particular situation is handled.
*
* @section talloc_performance 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 4% 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.
*
* @section talloc_named Named blocks
*
* Every talloc chunk has a name that can be used as a dynamic type-checking
* system. If for some reason like a callback function you had to cast a
* "struct foo *" to a "void *" variable, later you can safely reassign the
* "void *" pointer to a "struct foo *" by using the talloc_get_type() or
* talloc_get_type_abort() macros.
*
* @code
* struct foo *X = talloc_get_type_abort(ptr, struct foo);
* @endcode
*
* This will abort if "ptr" does not contain a pointer that has been created
* with talloc(mem_ctx, struct foo).
*
* @section talloc_threading Multi-threading
*
* talloc itself does not deal with threads. It is thread-safe (assuming the
* underlying "malloc" is), as long as each thread uses different memory
* contexts.
*
* If two threads uses the same context then they need to synchronize in order
* to be safe. In particular:
*
* - when using talloc_enable_leak_report(), giving directly NULL as a parent
* context implicitly refers to a hidden "null context" global variable, so
* this should not be used in a multi-threaded environment without proper
* synchronization.
* - the context returned by talloc_autofree_context() is also global so
* shouldn't be used by several threads simultaneously without
* synchronization.
*
*/

64
lib/talloc/talloc.h
View File

@ -35,70 +35,6 @@
* talloc is a hierarchical, reference counted memory pool system with
* destructors. It is the core memory allocator used in Samba.
*
* Perhaps the biggest difference from other memory pool systems is that there
* is no distinction between a "talloc context" and a "talloc pointer". Any
* pointer returned from talloc() is itself a valid talloc context. This means
* you can do this:
*
* @code
* struct foo *X = talloc(mem_ctx, struct foo);
* X->name = talloc_strdup(X, "foo");
* @endcode
*
* The pointer X->name would be a "child" of the talloc context "X" which is
* itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is all
* destroyed, whereas if you do talloc_free(X) then just X and X->name are
* destroyed, and if you do talloc_free(X->name) then just the name element of
* X is destroyed.
*
* If you think about this, then what this effectively gives you is an n-ary
* tree, where you can free any part of the tree with talloc_free().
*
* If you find this confusing, then run the testsuite to watch talloc in
* action. You may also like to add your own tests to testsuite.c to clarify
* how some particular situation is handled.
*
* @section talloc_performance 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 4% 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.
*
* @section talloc_named Named blocks
*
* Every talloc chunk has a name that can be used as a dynamic type-checking
* system. If for some reason like a callback function you had to cast a
* "struct foo *" to a "void *" variable, later you can safely reassign the
* "void *" pointer to a "struct foo *" by using the talloc_get_type() or
* talloc_get_type_abort() macros.
*
* @code
* struct foo *X = talloc_get_type_abort(ptr, struct foo);
* @endcode
*
* This will abort if "ptr" does not contain a pointer that has been created
* with talloc(mem_ctx, struct foo).
*
* @section talloc_threading Multi-threading
*
* talloc itself does not deal with threads. It is thread-safe (assuming the
* underlying "malloc" is), as long as each thread uses different memory
* contexts.
*
* If two threads uses the same context then they need to synchronize in order
* to be safe. In particular:
*
* - when using talloc_enable_leak_report(), giving directly NULL as a parent
* context implicitly refers to a hidden "null context" global variable, so
* this should not be used in a multi-threaded environment without proper
* synchronization.
* - the context returned by talloc_autofree_context() is also global so
* shouldn't be used by several threads simultaneously without
* synchronization.
*
* @{
*/