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.
You should start by reading The Tutorial, then reading the documentation of the interesting functions as you go.
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:
struct foo *X = talloc(mem_ctx, struct foo); X->name = talloc_strdup(X, "foo");
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.
struct foo *X = talloc_get_type_abort(ptr, struct foo);
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:
1.6.3