diff -r ec0ae0c8854e -r 151f5345f303 ucx/allocator.h
--- a/ucx/allocator.h Wed Jul 17 16:17:42 2013 +0200
+++ b/ucx/allocator.h Wed Jul 17 20:03:01 2013 +0200
@@ -25,9 +25,32 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
+/**
+ * Allocator for custom memory management.
+ *
+ * An UCX allocator consists of a pointer to the memory area / pool and four
+ * function pointers to memory management functions operating on this memory
+ * area / pool. These functions shall behave equivalent to the standard libc
+ * functions malloc(), calloc(), realloc()
and free()
.
+ *
+ * The signature of the memory management functions is based on the signature
+ * of the respective libc function but each of them takes the pointer to the
+ * memory area / pool as first argument.
+ *
+ * As the pointer to the memory area / pool can be arbitrarily chosen, any data
+ * can be provided to the memory management functions. An UcxMempool is just
+ * one example.
+ *
+ * @see mempool.h
+ * @see UcxMap
+ *
+ * @file allocator.h
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ */
-#ifndef ALLOCATOR_H
-#define ALLOCATOR_H
+#ifndef UCX_ALLOCATOR_H
+#define UCX_ALLOCATOR_H
#include "ucx.h"
@@ -35,26 +58,105 @@
extern "C" {
#endif
+/**
+ * A function pointer to the allocators malloc()
function.
+ * @see UcxAllocator
+ */
typedef void*(*ucx_allocator_malloc)(void *pool, size_t n);
+/**
+ * A function pointer to the allocators calloc()
function.
+ * @see UcxAllocator
+ */
typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size);
+/**
+ * A function pointer to the allocators realloc()
function.
+ * @see UcxAllocator
+ */
typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n);
+/**
+ * A function pointer to the allocators free()
function.
+ * @see UcxAllocator
+ */
typedef void(*ucx_allocator_free)(void *pool, void *data);
+/**
+ * UCX allocator data structure containing memory management functions.
+ */
typedef struct {
+ /** Pointer to an area of memory or a complex memory pool.
+ * This pointer will be passed to any memory management function as first
+ * argument.
+ */
void *pool;
+ /**
+ * The malloc()
function for this allocator.
+ */
ucx_allocator_malloc malloc;
+ /**
+ * The calloc()
function for this allocator.
+ */
ucx_allocator_calloc calloc;
+ /**
+ * The realloc()
function for this allocator.
+ */
ucx_allocator_realloc realloc;
+ /**
+ * The free()
function for this allocator.
+ */
ucx_allocator_free free;
} UcxAllocator;
+/**
+ * Returns a pointer to the default allocator.
+ *
+ * The default allocator contains wrappers to the standard libc memory
+ * management functions. Use this function to get a pointer to a globally
+ * available allocator. You may also define an own UcxAllocator by assigning
+ * #UCX_ALLOCATOR_DEFAULT to a variable and pass the address of this variable
+ * to any function that takes an UcxAllocator as argument. Note that using
+ * this function is the recommended way of passing a default allocator, thus
+ * it never runs out of scope.
+ *
+ * @return a pointer to the default allocator
+ *
+ * @see UCX_ALLOCATOR_DEFAULT
+ */
UcxAllocator *ucx_default_allocator();
+/**
+ * A wrapper for the standard libc malloc()
function.
+ * @param ignore ignored (may be used by allocators for pooled memory)
+ * @param n argument passed to malloc()
+ * @return return value of malloc()
+ */
void *ucx_default_malloc(void *ignore, size_t n);
+/**
+ * A wrapper for the standard libc calloc()
function.
+ * @param ignore ignored (may be used by allocators for pooled memory)
+ * @param n argument passed to calloc()
+ * @param size argument passed to calloc()
+ * @return return value of calloc()
+ */
void *ucx_default_calloc(void *ignore, size_t n, size_t size);
+/**
+ * A wrapper for the standard libc realloc()
function.
+ * @param ignore ignored (may be used by allocators for pooled memory)
+ * @param data argumend passed to realloc()
+ * @param n argument passed to realloc()
+ * @return return value of realloc()
+ */
void *ucx_default_realloc(void *ignore, void *data, size_t n);
+/**
+ * A wrapper for the standard libc free()
function.
+ * @param ignore ignored (may be used by allocators for pooled memory)
+ * @param data argument passed to free()
+ * @return return value of free()
+ */
void ucx_default_free(void *ignore, void *data);
+/**
+ * Convenient macro for a default allocator struct
definition.
+ */
#define UCX_ALLOCATOR_DEFAULT {NULL, \
ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \
ucx_default_free }
@@ -63,5 +165,5 @@
}
#endif
-#endif /* ALLOCATOR_H */
+#endif /* UCX_ALLOCATOR_H */