c: minor comment changes

c/Makefile

@@ -45,7 +45,6 @@ LDFLAGS   := -L$(LIBDIR)
 LDLIB     := -l$(LIB)
 
 export LD_LIBRARY_PATH = $(LIBDIR)
-#export PATH := .:$(PATH)
 
 .PHONY: all libs clean dirs
 

c/debug.c

@@ -1,6 +1,6 @@
 /* debug.c - debug/log management
  *
- * Copyright (C) 2021 Bruno Raoult ("br")
+ * Copyright (C) 2021-2022 Bruno Raoult ("br")
  * Licensed under the GNU General Public License v3.0 or later.
  * Some rights reserved. See COPYING.
  *

c/include/debug.h

@@ -37,48 +37,61 @@ static inline void _printf debug(_unused u32 level, _unused bool timestamp,
 #undef _unused
 #undef _printf
 
-/* format: only printf
+/**
+ * log - simple log (no function name, no indent, no timestamp)
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
  */
 #define log(level, fmt, args...) \
     debug((level), false, 0, NULL, 0, fmt, ##args)
 
-/* format : indent, no func name, no timestamp
+/**
+ * log_i - log with indent (no function name, no timestamp)
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
+ *
+ * Output example:
  * >>>>val=2
  */
 #define log_i(level, fmt, args...) \
     debug((level), false, (level), NULL, 0, fmt, ##args)
 
-/* format : func name, no indent, no timestamp
+/**
- * [foo] val=2
+ * log_f - log with function name (no indent name, no timestamp)
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
+ *
+ * Output example:
+ * [function] val=2
  */
 #define log_f(level, fmt, args...) \
     debug((level), false, 0, __func__, 0, fmt, ##args)
 
-/* format : func name, no indent, no timestamp
+/**
- * >>>> [foo:15] val=2
+ * log_if - log with function name and line number (no indent name, no timestamp)
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
+ *
+ * Output example:
+ * >>>> [function:15] val=2
  */
 #define log_if(level, fmt, args...) \
     debug((level), false, (level), __func__, __LINE__, fmt, ##args)
 
-/* format : func name, indent, timestamp
+/**
- * >>>>foo:15 val=2
+ * log_it - log with function name, line number, indent, and timestamp
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
+ *
+ * Output example:
+ * >>>> [function:15] val=2
  */
 #define log_it(level, fmt, args...) \
     debug((level), true, (level), __func__, __LINE__, fmt, ##args)
 
-/* format: file name, no indent, no timestamp
+#endif /* DEBUG_H */
- * foo:15 val=2
- *
- * #define log_f(level, fmt, args...)                            \
- *   debug((level), false, 0, __FILE__, __LINE__, fmt, args)
- */
-
-#else
-#define log(level, fmt, args...)
-#define log_i(...)
-#define log_f(...)
-#define log_if(...)
-#define log_it(...)
-#define log_f(...)
-
-#endif  /* DEBUG_H */

c/include/pool.h

@@ -28,10 +28,10 @@ typedef struct {
 
 typedef struct {
     char name[POOL_NAME_LENGTH];                  /* pool name */
+    size_t eltsize;                               /* object size */
     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 */
@@ -48,29 +48,42 @@ void pool_stats(pool_t *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.
+ *
+ * The name will be truncated to 16 characters (including the final '\0').
+ *
+ * Return:   The address of the created pool, or NULL if error.
  */
 pool_t *pool_create(const char *name, u32 grow, size_t size);
 
 /**
- * pool_get - get an element from a pool
+ * pool_get() - Get an element from a pool.
- * @pool:    the pool address.
+ * @pool:    The pool address.
+ *
+ * Get an object from the pool.
+ *
+ * Return:   The address of the object, or NULL if error.
  */
 void *pool_get(pool_t *pool);
 
 /**
- * pool_add - add (release) an element to a pool
+ * pool_add() - Add (free) an element to a pool.
- * @pool:    the pool address.
+ * @pool:    The pool address.
- * @elt:     the address of the object to add to the pool.
+ * @elt:     The address of the object to add to the pool.
+ *
+ * The object will be available for further pool_get().
+ *
+ * Return:   The current number of available elements in pool (including
+ *           @elt).
  */
 u32 pool_add(pool_t *pool, void *elt);
 
 /**
- * pool_destroy - destroy a pool.
+ * pool_destroy() - destroy a pool.
- * @pool:    the pool address.
+ * @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
+ * elements have been released. Referencing any pool object after this call
- * is strongly discouraged.
+ * will likely imply some memory corruption.
  */
 void pool_destroy(pool_t *pool);
 

c/pool.c

@@ -1,6 +1,6 @@
 /* pool.c - A simple pool manager.
  *
- * Copyright (C) 2021 Bruno Raoult ("br")
+ * Copyright (C) 2021-2022 Bruno Raoult ("br")
  * Licensed under the GNU General Public License v3.0 or later.
  * Some rights reserved. See COPYING.
  *
@@ -25,7 +25,6 @@
 void pool_stats(pool_t *pool)
 {
     if (pool) {
-#       ifdef DEBUG_POOL
         block_t *block;
 
         log_f(1, "[%s] pool [%p]: blocks:%u avail:%u alloc:%u grow:%u eltsize:%lu\n",
@@ -36,7 +35,6 @@ void pool_stats(pool_t *pool)
             log(5, "%p ", block);
         }
         log(5, "\n");
-#       endif
     }
 }
 
@@ -67,6 +65,8 @@ pool_t *pool_create(const char *name, u32 growsize, size_t eltsize)
         pool->nblocks = 0;
         INIT_LIST_HEAD(&pool->list_available);
         INIT_LIST_HEAD(&pool->list_blocks);
+    } else {
+        errno = ENOMEM;
     }
     return pool;
 }
@@ -105,9 +105,6 @@ void *pool_get(pool_t *pool)
         return NULL;
     if (!pool->available) {
         block_t *block = malloc(sizeof(block_t) + pool->eltsize * pool->growsize);
-        void *cur;
-        u32 i;
-
         if (!block) {
 #           ifdef DEBUG_POOL
             log_f(1, "[%s]: failed block allocation\n", pool->name);
@@ -131,16 +128,15 @@ void *pool_get(pool_t *pool)
 #       endif
 
         pool->allocated += pool->growsize;
-        for (i = 0; i < pool->growsize; ++i) {
+        for (u32 i = 0; i < pool->growsize; ++i) {
-            cur = block->data + i * pool->eltsize;
+            void *cur = block->data + i * pool->eltsize;
 #           ifdef DEBUG_POOL
             log_f(7, "alloc=%p cur=%p\n", block, cur);
 #           endif
             _pool_add(pool, (struct list_head *)cur);
         }
-        //pool_stats(pool);
     }
-    /* this is the effective address if the object (and also the
+    /* this is the effective address of the object (and also the
      * pool list_head address)
      */
     return _pool_get(pool);
@@ -221,5 +217,6 @@ int main(int ac, char**av)
         }
     }
     pool_stats(pool);
+    pool_destroy(pool);
 }
 #endif