ctdb/lib/talloc/doc/mainpage.dox

   1 /**
   2  * @mainpage
   3  *
   4  * talloc is a hierarchical, reference counted memory pool system with
   5  * destructors. It is the core memory allocator used in Samba.
   6  *
   7  * @section talloc_download Download
   8  *
   9  * You can download the latest releases of talloc from the
  10  * <a href="http://samba.org/ftp/talloc" target="_blank">talloc directory</a>
  11  * on the samba public source archive.
  12  *
  13  * @section talloc_bugs Discussion and bug reports
  14  *
  15  * talloc does not currently have its own mailing list or bug tracking system.
  16  * For now, please use the
  17  * <a href="https://lists.samba.org/mailman/listinfo/samba-technical" target="_blank">samba-technical</a>
  18  * mailing list, and the
  19  * <a href="http://bugzilla.samba.org/" target="_blank">Samba bugzilla</a>
  20  * bug tracking system.
  21  *
  22  * @section talloc_devel Development
  23  * You can download the latest code either via git or rsync.
  24  *
  25  * To fetch via git see the following guide:
  26  *
  27  * <a href="http://wiki.samba.org/index.php/Using_Git_for_Samba_Development" target="_blank">Using Git for Samba Development</a>
  28  *
  29  * Once you have cloned the tree switch to the master branch and cd into the
  30  * lib/tevent directory.
  31  *
  32  * To fetch via rsync use this command:
  33  *
  34  * rsync -Pavz samba.org::ftp/unpacked/standalone_projects/lib/talloc .
  35  *
  36  * @section talloc_preample Preamble
  37  *
  38  * talloc is a hierarchical, reference counted memory pool system with
  39  * destructors.
  40  *
  41  * Perhaps the biggest difference from other memory pool systems is that there
  42  * is no distinction between a "talloc context" and a "talloc pointer". Any
  43  * pointer returned from talloc() is itself a valid talloc context. This means
  44  * you can do this:
  45  *
  46  * @code
  47  *      struct foo *X = talloc(mem_ctx, struct foo);
  48  *      X->name = talloc_strdup(X, "foo");
  49  * @endcode
  50  *
  51  * The pointer X->name would be a "child" of the talloc context "X" which is
  52  * itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is all
  53  * destroyed, whereas if you do talloc_free(X) then just X and X->name are
  54  * destroyed, and if you do talloc_free(X->name) then just the name element of
  55  * X is destroyed.
  56  *
  57  * If you think about this, then what this effectively gives you is an n-ary
  58  * tree, where you can free any part of the tree with talloc_free().
  59  *
  60  * If you find this confusing, then run the testsuite to watch talloc in
  61  * action. You may also like to add your own tests to testsuite.c to clarify
  62  * how some particular situation is handled.
  63  *
  64  * @section talloc_performance Performance
  65  *
  66  * All the additional features of talloc() over malloc() do come at a price. We
  67  * have a simple performance test in Samba4 that measures talloc() versus
  68  * malloc() performance, and it seems that talloc() is about 4% slower than
  69  * malloc() on my x86 Debian Linux box. For Samba, the great reduction in code
  70  * complexity that we get by using talloc makes this worthwhile, especially as
  71  * the total overhead of talloc/malloc in Samba is already quite small.
  72  *
  73  * @section talloc_named Named blocks
  74  *
  75  * Every talloc chunk has a name that can be used as a dynamic type-checking
  76  * system. If for some reason like a callback function you had to cast a
  77  * "struct foo *" to a "void *" variable, later you can safely reassign the
  78  * "void *" pointer to a "struct foo *" by using the talloc_get_type() or
  79  * talloc_get_type_abort() macros.
  80  *
  81  * @code
  82  *      struct foo *X = talloc_get_type_abort(ptr, struct foo);
  83  * @endcode
  84  *
  85  * This will abort if "ptr" does not contain a pointer that has been created
  86  * with talloc(mem_ctx, struct foo).
  87  *
  88  * @section talloc_threading Multi-threading
  89  *
  90  * talloc itself does not deal with threads. It is thread-safe (assuming the
  91  * underlying "malloc" is), as long as each thread uses different memory
  92  * contexts.
  93  *
  94  * If two threads uses the same context then they need to synchronize in order
  95  * to be safe. In particular:
  96  *
  97  *   - when using talloc_enable_leak_report(), giving directly NULL as a parent
  98  *     context implicitly refers to a hidden "null context" global variable, so
  99  *     this should not be used in a multi-threaded environment without proper
 100  *     synchronization.
 101  *   - the context returned by talloc_autofree_context() is also global so
 102  *     shouldn't be used by several threads simultaneously without
 103  *     synchronization.
 104  *
 105  */