Mercurial > hg > ucx / changeset

--- 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 <code>malloc(), calloc(), realloc()</code> and <code>free()</code>.
+ * 
+ * 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 <code>malloc()</code> function.
+ * @see UcxAllocator
+ */
 typedef void*(*ucx_allocator_malloc)(void *pool, size_t n);
+/**
+ * A function pointer to the allocators <code>calloc()</code> function.
+ * @see UcxAllocator
+ */
 typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size);
+/**
+ * A function pointer to the allocators <code>realloc()</code> function.
+ * @see UcxAllocator
+ */
 typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n);
+/**
+ * A function pointer to the allocators <code>free()</code> 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 <code>malloc()</code> function for this allocator.
+     */
     ucx_allocator_malloc  malloc;
+    /**
+     * The <code>calloc()</code> function for this allocator.
+     */
     ucx_allocator_calloc  calloc;
+    /**
+     * The <code>realloc()</code> function for this allocator.
+     */
     ucx_allocator_realloc realloc;
+    /**
+     * The <code>free()</code> 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 <code>malloc()</code> function.
+ * @param ignore ignored (may be used by allocators for pooled memory)
+ * @param n argument passed to <code>malloc()</code>
+ * @return return value of <code>malloc()</code>
+ */
 void *ucx_default_malloc(void *ignore, size_t n);
+/**
+ * A wrapper for the standard libc <code>calloc()</code> function.
+ * @param ignore ignored (may be used by allocators for pooled memory)
+ * @param n argument passed to <code>calloc()</code>
+ * @param size  argument passed to <code>calloc()</code>
+ * @return return value of <code>calloc()</code>
+ */
 void *ucx_default_calloc(void *ignore, size_t n, size_t size);
+/**
+ * A wrapper for the standard libc <code>realloc()</code> function.
+ * @param ignore ignored (may be used by allocators for pooled memory)
+ * @param data argumend passed to <code>realloc()</code>
+ * @param n argument passed to <code>realloc()</code>
+ * @return return value of <code>realloc()</code>
+ */
 void *ucx_default_realloc(void *ignore, void *data, size_t n);
+/**
+ * A wrapper for the standard libc <code>free()</code> function.
+ * @param ignore ignored (may be used by allocators for pooled memory)
+ * @param data argument passed to <code>free()</code>
+ * @return return value of <code>free()</code>
+ */
 void ucx_default_free(void *ignore, void *data);
 
+/**
+ * Convenient macro for a default allocator <code>struct</code> 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 */
 

--- a/ucx/string.h	Wed Jul 17 16:17:42 2013 +0200
+++ b/ucx/string.h	Wed Jul 17 20:03:01 2013 +0200
@@ -183,12 +183,48 @@
  * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
  * <code>free()</code>.
  * 
+ * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
+ * terminated.
+ * 
  * @param string the string to duplicate
- * @return a duplicate of the argument
+ * @return a duplicate of the string
  */
 sstr_t sstrdup(sstr_t string);
-sstr_t sstrdupa(UcxAllocator *allocator, sstr_t s);
+
+/**
+ * Creates a duplicate of the specified string using an UcxAllocator.
+ * 
+ * The new sstr_t will contain a copy allocated by the allocators
+ * ucx_allocator_malloc function. So it is implementation depended, whether the
+ * returned sstr_t.ptr pointer must be passed to the allocators
+ * ucx_allocator_free function manually.
+ * 
+ * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
+ * terminated.
+ * 
+ * @param allocator a valid instance of an UcxAllocator
+ * @param string the string to duplicate
+ * @return a duplicate of the string
+ */
+sstr_t sstrdupa(UcxAllocator *allocator, sstr_t string);
 
+/**
+ * Omits leading and trailing spaces.
+ * 
+ * This function returns a new sstr_t containing a trimmed version of the
+ * specified string.
+ * 
+ * <b>Note:</b> the new sstr_t references the same memory, thus you
+ * <b>MUST NOT</b> pass the sstr_t.ptr of the return value to
+ * <code>free()</code>. It is also highly recommended to avoid assignments like
+ * <code>mystr = sstrtrim(mystr);</code> as you lose the reference to the
+ * source string. Assignments of this type are only permitted, if the
+ * sstr_t.ptr of the source string does not need to be freed or if another
+ * reference to the source string exists.
+ * 
+ * @param string the string that shall be trimmed
+ * @return a new sstr_t containing the trimmed string
+ */
 sstr_t sstrtrim(sstr_t string);
 
 #ifdef	__cplusplus