diff options
| -rw-r--r-- | lib/talloc/doc/mainpage.dox | 69 | ||||
| -rw-r--r-- | lib/talloc/talloc.h | 64 |
2 files changed, 69 insertions, 64 deletions
diff --git a/lib/talloc/doc/mainpage.dox b/lib/talloc/doc/mainpage.dox index 9629949124..3204e8a5c2 100644 --- a/lib/talloc/doc/mainpage.dox +++ b/lib/talloc/doc/mainpage.dox @@ -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. + * */ diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h index 17f7dc1060..349209070a 100644 --- a/lib/talloc/talloc.h +++ b/lib/talloc/talloc.h @@ -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. - * * @{ */ |