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