From 026358b2c904d3e5677928fefc625ca52a0c90a1 Mon Sep 17 00:00:00 2001
From: Pavel Charvat <pchar@ucw.cz>
Date: Mon, 10 Nov 2008 13:19:12 +0100
Subject: [PATCH] Doc: Briefly documented eltpools.

---
 ucw/doc/Makefile    |  2 +-
 ucw/doc/eltpool.txt | 12 ++++++++++
 ucw/doc/index.txt   |  1 +
 ucw/eltpool.h       | 55 ++++++++++++++++++++++++++++++++++++++++-----
 4 files changed, 64 insertions(+), 6 deletions(-)
 create mode 100644 ucw/doc/eltpool.txt

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index b6b713df..e5a4c926 100644
--- a/ucw/doc/Makefile
+++ b/ucw/doc/Makefile
@@ -2,7 +2,7 @@
 
 DIRS+=ucw/doc
 
-UCW_DOCS=fastbuf index config configure install basecode hash docsys conf mempool mainloop generic growbuf unaligned lists chartype unicode
+UCW_DOCS=fastbuf index config configure install basecode hash docsys conf mempool eltpool mainloop generic growbuf unaligned lists chartype unicode
 UCW_INDEX=$(o)/ucw/doc/def_index.html
 UCW_DOCS_HTML=$(addprefix $(o)/ucw/doc/,$(addsuffix .html,$(UCW_DOCS)))
 
diff --git a/ucw/doc/eltpool.txt b/ucw/doc/eltpool.txt
new file mode 100644
index 00000000..080254e3
--- /dev/null
+++ b/ucw/doc/eltpool.txt
@@ -0,0 +1,12 @@
+Fixed-sized alocators
+=====================
+
+You can use them for efficient allocation of large amount of small
+fixed-sized memory blocks and to free them all at once.
+If you need more features, see more complex <<mempool:,memory pools>>.
+
+* <<defs,Definitions>>
+* <<basic,Basic manipulation>>
+* <<alloc,Allocation routines>>
+
+!!ucw/eltpool.h
diff --git a/ucw/doc/index.txt b/ucw/doc/index.txt
index d0410619..1fc17b7c 100644
--- a/ucw/doc/index.txt
+++ b/ucw/doc/index.txt
@@ -19,6 +19,7 @@ Modules
 - <<hash:,Hashing routines>>
 - <<conf:,Configuration and command line parser>>
 - <<mempool:,Memory pools>>
+- <<eltpool:,Fixed-sized allocators>>
 - <<mainloop:,Mainloop>>
 - <<unaligned:,Unaligned data>>
 - <<lists:,Link lists>>
diff --git a/ucw/eltpool.h b/ucw/eltpool.h
index 795a45e9..a3a4e427 100644
--- a/ucw/eltpool.h
+++ b/ucw/eltpool.h
@@ -10,6 +10,16 @@
 #ifndef _UCW_ELTPOOL_H
 #define _UCW_ELTPOOL_H
 
+/***
+ * [[defs]]
+ * Definitions
+ * -----------
+ ***/
+
+/**
+ * Memory pool of fixed-sized elements.
+ * You should use this one as an opaque handle only, the insides are internal.
+ **/
 struct eltpool {
   struct eltpool_chunk *first_chunk;
   struct eltpool_free *first_free;
@@ -29,13 +39,44 @@ struct eltpool_free {
   struct eltpool_free *next;
 };
 
+/***
+ * [[basic]]
+ * Basic manipulation
+ * ------------------
+ ***/
+
+/**
+ * Create a new memory pool for elements of @elt_size bytes.
+ * The pool will allocate chunks of at least @elts_per_chunk elements.
+ * Higher numbers lead to better allocation times but also to bigger
+ * unused memory blocks. Call @ep_delete() to free all pool's resources.
+ **/
 struct eltpool *ep_new(uns elt_size, uns elts_per_chunk);
+
+/**
+ * Release a memory pool created by @ep_new() including all
+ * elements allocated from that pool.
+ **/
 void ep_delete(struct eltpool *pool);
-void *ep_alloc_slow(struct eltpool *pool);
+
+/**
+ * Return the total number of bytes allocated by a given
+ * memory pool including all internals.
+ **/
 u64 ep_total_size(struct eltpool *pool);
 
-static inline void *
-ep_alloc(struct eltpool *pool)
+/***
+ * [[alloc]]
+ * Allocation routines
+ * -------------------
+ ***/
+
+void *ep_alloc_slow(struct eltpool *pool); /* Internal. Do not call directly. */
+/**
+ * Allocate a new element on a given memory pool.
+ * The results is always aligned to a multiple of the element's size.
+ **/
+static inline void *ep_alloc(struct eltpool *pool)
 {
   pool->num_allocated++;
 #ifdef CONFIG_FAKE_ELTPOOL
@@ -50,8 +91,12 @@ ep_alloc(struct eltpool *pool)
 #endif
 }
 
-static inline void
-ep_free(struct eltpool *pool, void *p)
+/**
+ * Release an element previously allocated by @ep_alloc().
+ * Note thet the memory is not really freed (until @mp_delete()),
+ * but it can be reused by future @ep_alloc()'s.
+ **/
+static inline void ep_free(struct eltpool *pool, void *p)
 {
   pool->num_allocated--;
 #ifdef CONFIG_FAKE_ELTPOOL
-- 
2.39.5