Doc: Briefly documented eltpools.

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index b6b713dfa052be07682545a49894ccf843698579..e5a4c926385587fae2d44336d39e6ef3ec0f6bb8 100644 (file)
--- 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 (file)
index 0000000..080254e
--- /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 d04106199ad0ff55544c892064b93a568a1cec0e..1fc17b7c5137bc24c06e21830a00f8460a317c7d 100644 (file)
--- 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 795a45e997dc7957519fd5118ffb852b2ad93b07..a3a4e427a517d29d92be92c5c88a3866d03ba57f 100644 (file)
--- 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