/** * @mainpage * * talloc is a hierarchical, reference counted memory pool system with * destructors. It is the core memory allocator used in Samba. * * @section talloc_download Download * * You can download the latest releases of talloc from the * <a href="http://samba.org/ftp/talloc" target="_blank">talloc directory</a> * on the samba public source archive. * * @section talloc_bugs Discussion and bug reports * * talloc does not currently have its own mailing list or bug tracking system. * For now, please use the * <a href="https://lists.samba.org/mailman/listinfo/samba-technical" target="_blank">samba-technical</a> * mailing list, and the * <a href="http://bugzilla.samba.org/" target="_blank">Samba bugzilla</a> * bug tracking system. * * @section talloc_devel Development * You can download the latest code either via git or rsync. * * To fetch via git see the following guide: * * <a href="http://wiki.samba.org/index.php/Using_Git_for_Samba_Development" target="_blank">Using Git for Samba Development</a> * * 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 . * * @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. * */