talloc: add ASCII art to describe parent/child arrangement

Signed-off-by: Andrew Bartlett <abartlet@samba.org>
Reviewed-by: Garming Sam <garming@catalyst.net.nz>

1 files changed, 25 insertions, 0 deletions

diff --git a/lib/talloc/talloc.c b/lib/talloc/talloc.c
index 927b7f5e5f8..a097ce088df 100644
--- a/lib/talloc/talloc.c
+++ b/lib/talloc/talloc.c
@@ -263,7 +263,32 @@ typedef int (*talloc_destructor_t)(void *);
 struct talloc_pool_hdr;
 
 struct talloc_chunk {
+	/*
+	 * flags includes the talloc magic, which is randomised to
+	 * make overwrite attacks harder
+	 */
 	unsigned flags;
+
+	/*
+	 * If you have a logical tree like:
+	 *
+	 *           <parent>
+	 *           /   |   \
+	 *          /    |    \
+	 *         /     |     \
+	 * <child 1> <child 2> <child 3>
+	 *
+	 * The actual talloc tree is:
+	 *
+	 *  <parent>
+	 *     |
+	 *  <child 1> - <child 2> - <child 3>
+	 *
+	 * The children are linked with next/prev pointers, and
+	 * child 1 is linked to the parent with parent/child
+	 * pointers.
+	 */
+
 	struct talloc_chunk *next, *prev;
 	struct talloc_chunk *parent, *child;
 	struct talloc_reference_handle *refs;