lib: Document datastack mempools

diff --git a/src/lib/mempool-datastack.c b/src/lib/mempool-datastack.c
index 6a66b118b07b34c669f747a51166794fbd0e03d7..e3971d1a9953a384c15cef376bc66540cf0eee3e 100644 (file)
--- a/src/lib/mempool-datastack.c
+++ b/src/lib/mempool-datastack.c
@@ -3,6 +3,57 @@
 #include "lib.h"
 #include "mempool.h"
 
+/*
+ * The datastack pool is a thin wrapper around the datastack API.  It exists
+ * to allow datastack allocations via the pool API.
+ *
+ * Note: Do not confuse it with the *unsafe* datastack pool.
+ *
+ * Implementation
+ * ==============
+ *
+ * A datastack pool maintains information about the datastack frame that was
+ * in use when the pool was created so it can sanity check all p_new(),
+ * p_malloc(), and p_realloc() calls.
+ *
+ * Creation
+ * --------
+ *
+ * When a datastack pool is created, a new pool structure is allocated from
+ * the datastack (via t_new()).  The current datastack frame number is saved
+ * into the pool's private data (struct datastack_pool).
+ *
+ * Allocation & Reallocation
+ * -------------------------
+ *
+ * After verifying that the saved datastack frame id matches the currently
+ * active one, the p_malloc() and p_realloc() calls get directed to
+ * t_malloc0() and t_try_realloc(), respectively.  There is no
+ * per-allocation information to track.
+ *
+ * Freeing
+ * -------
+ *
+ * Freeing is a no-op unless the currently active data stack frame id is
+ * different from the one saved during pool creation, in which case the
+ * process panics.
+ *
+ * Clearing
+ * --------
+ *
+ * A no-op.
+ *
+ * Destruction
+ * -----------
+ *
+ * Since the memory backing the pool structure itself is allocated from the
+ * datastack via t_new(), the pool and all allocations it made are freed
+ * when the datastack frame is popped.
+ *
+ * Even though the pool maintains a reference count, no memory is freed when
+ * it reaches zero.  Once the reference count reaches zero, the state of the
+ * pool is undefined and none of its memory maybe be used.
+ */
 
 static const char *pool_data_stack_get_name(pool_t pool);
 static void pool_data_stack_ref(pool_t pool);