talloc Documentation
2.0
talloc is a hierarchical, reference counted memory pool system with destructors. It is the core memory allocator used in Samba.
You can download the latest releases of talloc from the
talloc directory on the samba public source archive.
talloc does not currently have its own mailing list or bug tracking system. For now, please use the
samba-technical mailing list, and the
Samba bugzilla bug tracking system.
You can download the latest code either via git or rsync.
To fetch via git see the following guide:
Using Git for Samba Development
Once you have cloned the tree switch to the master branch and cd into the lib/tevent directory.
To fetch via rsync use this command:
rsync -Pavz samba.org::ftp/unpacked/standalone_projects/lib/talloc .
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:
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.
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.
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.
This will abort if "ptr" does not contain a pointer that has been created with talloc(mem_ctx, struct foo).
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.
