Main: Tests now include main_cleanup()

[libucw.git] / ucw / eltpool.h

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