lib: Document the system mempool

diff --git a/src/lib/mempool-system.c b/src/lib/mempool-system.c
index 7686ac4eb9d5bc03308dd780798ca1aa7382e929..507b70a73d18d14c16b0e8e69f2e502c64b6a6ab 100644 (file)
--- a/src/lib/mempool-system.c
+++ b/src/lib/mempool-system.c
@@ -6,6 +6,39 @@
 #include "safe-memset.h"
 #include "mempool.h"
 
+/*
+ * The system pool is a thin wrapper around calloc() and free().  It exists
+ * to allow direct heap usage via the pool API.
+ *
+ * Implementation
+ * ==============
+ *
+ * Creation
+ * --------
+ *
+ * The system pool is created statically and therefore is available at any
+ * time.
+ *
+ * Allocation, Reallocation & Freeing
+ * ----------------------------------
+ *
+ * The p_malloc(), p_realloc(), and p_free() calls get directed to calloc(),
+ * realloc(), and free().  There is no additional per-allocation information
+ * to track.
+ *
+ * Clearing
+ * --------
+ *
+ * Not supported.  Attempting to clear the system pool will result in a
+ * panic.
+ *
+ * Destruction
+ * -----------
+ *
+ * It is not possible to destroy the system pool.  Any attempt to unref the
+ * pool is a no-op.
+ */
+
 #ifndef HAVE_MALLOC_USABLE_SIZE
 /* no extra includes needed */
 #elif defined (HAVE_MALLOC_NP_H)