# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1376051814 -7200
# Node ID a0aa1c15f46b1359f133f8c9c0b0f2a4a0e00f97
# Parent  4d320dc3a7af0b9582e91a203512b8e7d321ed74
documented mempool + some fixes

diff -r 4d320dc3a7af -r a0aa1c15f46b ucx/mempool.c
--- a/ucx/mempool.c	Fri Aug 09 11:32:10 2013 +0200
+++ b/ucx/mempool.c	Fri Aug 09 14:36:54 2013 +0200
@@ -53,7 +53,9 @@
 
 UcxMempool *ucx_mempool_new(size_t n) {
     UcxMempool *pool = (UcxMempool*)malloc(sizeof(UcxMempool));
-    if (pool == NULL) return NULL;
+    if (!pool) {
+        return NULL;
+    }
     
     pool->data = (void**) malloc(n * sizeof(void*));
     if (pool->data == NULL) {
@@ -68,20 +70,23 @@
 
 int ucx_mempool_chcap(UcxMempool *pool, size_t newcap) {
     void **data = (void**) realloc(pool->data, newcap*sizeof(void*));
-    if (data == NULL) {
-        return 1;
-    } else {
+    if (data) {
         pool->data = data; 
         pool->size = newcap;
         return EXIT_SUCCESS;
+    } else {
+        return EXIT_FAILURE;
     }
 }
 
 void *ucx_mempool_malloc(UcxMempool *pool, size_t n) {
     ucx_memchunk *mem = (ucx_memchunk*)malloc(sizeof(ucx_destructor) + n);
-    if (mem == NULL) return NULL;
+    if (!mem) {
+        return NULL;
+    }
 
     if (pool->ndata >= pool->size) {
+        // The hard coded 16 is documented for this function and ucx_mempool_new
         ucx_mempool_chcap(pool, pool->size + 16);
      }
 
@@ -89,12 +94,12 @@
     pool->data[pool->ndata] = mem;
     pool->ndata++;
 
-    return &mem->c;
+    return &(mem->c);
 }
 
 void *ucx_mempool_calloc(UcxMempool *pool, size_t nelem, size_t elsize) {
     void *ptr = ucx_mempool_malloc(pool, nelem*elsize);
-    if(ptr == NULL) {
+    if (!ptr) {
         return NULL;
     }
     memset(ptr, 0, nelem * elsize);
@@ -104,7 +109,9 @@
 void *ucx_mempool_realloc(UcxMempool *pool, void *ptr, size_t n) {
     char *mem = ((char*)ptr) - sizeof(ucx_destructor);
     char *newm = (char*) realloc(mem, n + sizeof(ucx_destructor));
-    if (newm == NULL) return NULL;
+    if (!newm) {
+        return NULL;
+    }
     if (mem != newm) {
         for(size_t i=0 ; i < pool->ndata ; i++) {
             if(pool->data[i] == mem) {
@@ -138,7 +145,7 @@
     }
     fprintf(stderr, "FATAL: 0x%08" PRIxPTR" not in mpool 0x%08" PRIxPTR"\n",
             (intptr_t)ptr, (intptr_t)pool);
-    exit(1);
+    exit(EXIT_FAILURE);
 }
 
 void ucx_mempool_destroy(UcxMempool *pool) {
@@ -146,8 +153,8 @@
     for(size_t i=0 ; i<pool->ndata ; i++) {
         chunk = (ucx_memchunk*) pool->data[i];
         if(chunk) {
-            if(chunk->destructor != NULL) {
-                chunk->destructor(&chunk->c);
+            if(chunk->destructor) {
+                chunk->destructor(&(chunk->c));
             }
             free(chunk);
         }
diff -r 4d320dc3a7af -r a0aa1c15f46b ucx/mempool.h
--- a/ucx/mempool.h	Fri Aug 09 11:32:10 2013 +0200
+++ b/ucx/mempool.h	Fri Aug 09 14:36:54 2013 +0200
@@ -26,6 +26,15 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * @file mempool.h
+ * 
+ * Memory pool implementation.
+ * 
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ */
+
 #ifndef UCX_MEMPOOL_H
 #define	UCX_MEMPOOL_H
 
@@ -37,29 +46,154 @@
 extern "C" {
 #endif
 
+/**
+ * A function pointer to a destructor function.
+ * @see ucx_mempool_setdestr()
+ * @see ucx_mempool_regdestr()
+ */
 typedef void(*ucx_destructor)(void*);
 
+/**
+ * UCX mempool structure.
+ */
 typedef struct {
+    /** List of pointers to pooled memory. */
     void   **data;
+    /** Count of pooled memory items. */
     size_t ndata;
+    /** Memory pool size. */
     size_t size;
 } UcxMempool;
 
+/** Shorthand for a new default memory pool with a capacity of 16 elements. */
+#define ucx_mempool_new_default() ucx_mempool_new(16)
 
-#define ucx_mempool_new_default() ucx_mempool_new(16)
+
+/**
+ * Creates a memory pool with the specified initial size.
+ * 
+ * As the created memory pool automatically grows in size by 16 elements, when
+ * trying to allocate memory on a full pool, it is recommended that you use
+ * a multiple of 16 for the initial size.
+ * 
+ * @param n initial pool size (should be a multiple of 16)
+ * @return a pointer to the new memory pool
+ */
 UcxMempool *ucx_mempool_new(size_t n);
+
+/**
+ * Resizes a memory pool.
+ * 
+ * @param pool the pool to resize
+ * @param newcap the new capacity
+ * @return <code>EXIT_SUCCESS</code> on success or
+ * <code>EXIT_FAILURE</code> on failure
+ */
 int ucx_mempool_chcap(UcxMempool *pool, size_t newcap);
 
+/**
+ * Allocates pooled memory.
+ * 
+ * @param pool the memory pool
+ * @param n amount of memory to allocate
+ * @return a pointer to the allocated memory
+ * @see ucx_allocator_malloc()
+ */
 void *ucx_mempool_malloc(UcxMempool *pool, size_t n);
+/**
+ * Allocates a pooled memory array.
+ * 
+ * The contents of the allocated memory is set to zero.
+ * 
+ * @param pool the memory pool
+ * @param nelem amount of elements to allocate
+ * @param elsize amount of memory per element
+ * @return a pointer to the allocated memory
+ * @see ucx_allocator_calloc()
+ */
 void *ucx_mempool_calloc(UcxMempool *pool, size_t nelem, size_t elsize);
+/**
+ * Reallocates pooled memory.
+ * 
+ * @param pool the memory pool
+ * @param ptr a pointer to the memory that shall be reallocated
+ * @param n the new size of the memory
+ * @return a pointer to the the location of the memory
+ * @see ucx_allocator_realloc()
+ */
 void *ucx_mempool_realloc(UcxMempool *pool, void *ptr, size_t n);
+/**
+ * Frees pooled memory.
+ * 
+ * Before freeing the memory, the specified destructor function (if any)
+ * is called.
+ * 
+ * If you specify memory, that is not pooled by the specified memory pool, this
+ * is considered as a severe error and an error message is written to
+ * <code>stderr</code> and the application is shut down with code
+ * <code>EXIT_FAILURE</code>.
+ * 
+ * @param pool the memory pool
+ * @param ptr a pointer to the memory that shall be freed
+ * @see ucx_mempool_set_destr()
+ */
 void ucx_mempool_free(UcxMempool *pool, void *ptr);
 
+/**
+ * Destroys a memory pool.
+ * 
+ * For each element the destructor function (if any) is called and the element
+ * is freed.
+ * 
+ * Each of the registered destructor function that has no corresponding element
+ * within the pool (namely those registered by ucx_mempool_reg_destr) is
+ * called interleaving with the element destruction, but with guarantee to the
+ * order in which they were registered (FIFO order).
+ * 
+ * 
+ * @param pool the mempool to destroy
+ */
 void ucx_mempool_destroy(UcxMempool *pool);
 
+/**
+ * Sets a destructor function for the specified memory.
+ * 
+ * The destructor is automatically called when the memory is freed or the
+ * pool is destroyed.
+ * 
+ * The only requirement for the specified memory is, that it <b>MUST</b> be
+ * pooled memory by an UcxMempool or an element-compatible mempool. The pointer
+ * to the destructor function is saved in a reserved area before the actual
+ * memory.
+ * 
+ * @param ptr pooled memory
+ * @param func a pointer to the destructor function
+ * @see ucx_mempool_free()
+ * @see ucx_mempool_destroy()
+ */
 void ucx_mempool_set_destr(void *ptr, ucx_destructor func);
+
+/**
+ * Registers a destructor function for the specified (non-pooled) memory.
+ * 
+ * This is useful, if you have memory that has not been allocated by a mempool,
+ * but shall be managed by a mempool.
+ * 
+ * This function creates an entry in the specified mempool and the memory will
+ * therefore (logically) convert to pooled memory.
+ * 
+ * @param pool the memory pool
+ * @param ptr data the destructor is registered for
+ * @param destr a pointer to the destructor function
+ */
 void ucx_mempool_reg_destr(UcxMempool *pool, void *ptr, ucx_destructor destr);
 
+/**
+ * Creates an UcxAllocator based on an UcxMempool.
+ * 
+ * @param pool the mempool to create the UcxAllocator for
+ * @return a new UcxAllocator based on the specified pool
+ */
 UcxAllocator* ucx_mempool_allocator(UcxMempool *pool);
 
 #ifdef	__cplusplus
diff -r 4d320dc3a7af -r a0aa1c15f46b ucx/test.h
--- a/ucx/test.h	Fri Aug 09 11:32:10 2013 +0200
+++ b/ucx/test.h	Fri Aug 09 14:36:54 2013 +0200
@@ -82,9 +82,10 @@
 
 #ifndef __FUNCTION__
 /**
- * Alias for the __func__ preprocessor macro.
- * Some compilers use __func__ and others use __FUNC__. We use __FUNC__ so we
- * define it for those compilers which use __func__.
+ * Alias for the <code>__func__</code> preprocessor macro.
+ * Some compilers use <code>__func__</code> and others use __FUNC__.
+ * We use __FUNC__ so we define it for those compilers which use
+ * <code>__func__</code>.
  */
 #define __FUNCTION__ __func__
 #endif
@@ -127,7 +128,8 @@
  * 
  * @param suite the suite, the test function shall be added to
  * @param test the test function to register
- * @return EXIT_SUCCESS on success or EXIT_FAILURE on failure
+ * @return <code>EXIT_SUCCESS</code> on success or
+ * <code>EXIT_FAILURE</code> on failure
  */
 int ucx_test_register(UcxTestSuite* suite, UcxTest test);
 /**
diff -r 4d320dc3a7af -r a0aa1c15f46b ucx/utils.h
--- a/ucx/utils.h	Fri Aug 09 11:32:10 2013 +0200
+++ b/ucx/utils.h	Fri Aug 09 14:36:54 2013 +0200
@@ -26,6 +26,15 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * @file utils.h
+ * 
+ * Common utilities like compare and copy functions.
+ * 
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ */
+
 #ifndef UCX_UTILS_H
 #define	UCX_UTILS_H