/**

 * @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

 * talloc directory

 * on the samba public source archive.

 *

 * @section main-tutorial Tutorial

 *

 * You should start by reading @subpage libtalloc_tutorial, then reading the documentation of

 * the interesting functions as you go.

 * @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

 * samba-technical

 * mailing list, and the

 * Samba bugzilla

 * 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:

 *

 * 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 .

 *

 * @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. In threaded code turn off null tracking using

 *     talloc_disable_null_tracking().

 *   - the context returned by talloc_autofree_context() is also global so

 *     shouldn't be used by several threads simultaneously without

 *     synchronization.

 *

 */