From: Josef 'Jeff' Sipek <jeff.sipek@dovecot.fi>
Date: Tue, 19 Jun 2018 20:08:40 +0000 (-0400)
Subject: lib: Document the system mempool
X-Git-Tag: 2.3.9~1626
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7d0b693c1792b88fcfed9b523890c1073f794def;p=thirdparty%2Fdovecot%2Fcore.git

lib: Document the system mempool
---

diff --git a/src/lib/mempool-system.c b/src/lib/mempool-system.c
index 7686ac4eb9..507b70a73d 100644
--- 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)