refactor pool_init -> pool_create

2021/include/pool.h

@@ -20,25 +20,56 @@
 #include "bits.h"
 
 typedef struct {
-    struct list_head list_blocks;
-    char data[];
+    struct list_head list_blocks;                 /* list of allocated blocks in pool */
+    char data[];                                  /* objects block */
 } block_t;
 
 typedef struct {
-    char *name;
-    u32 available;
-    u32 allocated;
-    u32 growsize;
-    size_t eltsize;
-    u32 nblocks;
+    char *name;                                   /* pool name */
+    u32 available;                                /* current available elements */
+    u32 allocated;                                /* total objects allocated */
+    u32 growsize;                                 /* number of objects per block allocated */
+    size_t eltsize;                               /* object size */
+    u32 nblocks;                                  /* number of blocks allocated */
     struct list_head list_available;              /* available nodes */
     struct list_head list_blocks;                 /* allocated blocks */
 } pool_t;
 
+/**
+ * pool_stats - display some pool statistics
+ * @pool:    the pool address.
+ */
 void pool_stats(pool_t *pool);
-pool_t *pool_init(const char *name, u32 grow, size_t size);
+
+/**
+ * pool_create - create a new memory pool
+ * @name:    the name to give to the pool.
+ * @grow:    the number of elements to add when no more available.
+ * @size:    the size of an element in pool.
+ */
+pool_t *pool_create(const char *name, u32 grow, size_t size);
+
+/**
+ * pool_get - get an element from a pool
+ * @pool:    the pool address.
+ */
 void *pool_get(pool_t *pool);
+
+/**
+ * pool_add - add (release) an element to a pool
+ * @pool:    the pool address.
+ * @elt:     the address of the object to add to the pool.
+ */
 u32 pool_add(pool_t *pool, void *elt);
+
+/**
+ * pool_destroy - destroy a pool.
+ * @pool:    the pool address.
+ *
+ * Attention: All memory is freed, but no check is done whether all pool
+ * elements has been released. Referencing any pool object after this call
+ * is strongly discouraged.
+ */
 void pool_destroy(pool_t *pool);
 
 #endif