Mercurial > hg > ucx / changeset

     1.1 --- a/ucx/allocator.h	Wed Jul 17 16:17:42 2013 +0200
     1.2 +++ b/ucx/allocator.h	Wed Jul 17 20:03:01 2013 +0200
     1.3 @@ -25,9 +25,32 @@
     1.4   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     1.5   * POSSIBILITY OF SUCH DAMAGE.
     1.6   */
     1.7 +/**
     1.8 + * Allocator for custom memory management.
     1.9 + * 
    1.10 + * An UCX allocator consists of a pointer to the memory area / pool and four
    1.11 + * function pointers to memory management functions operating on this memory
    1.12 + * area / pool. These functions shall behave equivalent to the standard libc
    1.13 + * functions <code>malloc(), calloc(), realloc()</code> and <code>free()</code>.
    1.14 + * 
    1.15 + * The signature of the memory management functions is based on the signature
    1.16 + * of the respective libc function but each of them takes the pointer to the
    1.17 + * memory area / pool as first argument.
    1.18 + * 
    1.19 + * As the pointer to the memory area / pool can be arbitrarily chosen, any data
    1.20 + * can be provided to the memory management functions. An UcxMempool is just
    1.21 + * one example.
    1.22 + * 
    1.23 + * @see mempool.h
    1.24 + * @see UcxMap
    1.25 + * 
    1.26 + * @file   allocator.h
    1.27 + * @author Mike Becker
    1.28 + * @author Olaf Wintermann
    1.29 + */
    1.30  
    1.31 -#ifndef ALLOCATOR_H
    1.32 -#define	ALLOCATOR_H
    1.33 +#ifndef UCX_ALLOCATOR_H
    1.34 +#define	UCX_ALLOCATOR_H
    1.35  
    1.36  #include "ucx.h"
    1.37  
    1.38 @@ -35,26 +58,105 @@
    1.39  extern "C" {
    1.40  #endif
    1.41  
    1.42 +/**
    1.43 + * A function pointer to the allocators <code>malloc()</code> function.
    1.44 + * @see UcxAllocator
    1.45 + */
    1.46  typedef void*(*ucx_allocator_malloc)(void *pool, size_t n);
    1.47 +/**
    1.48 + * A function pointer to the allocators <code>calloc()</code> function.
    1.49 + * @see UcxAllocator
    1.50 + */
    1.51  typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size);
    1.52 +/**
    1.53 + * A function pointer to the allocators <code>realloc()</code> function.
    1.54 + * @see UcxAllocator
    1.55 + */
    1.56  typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n);
    1.57 +/**
    1.58 + * A function pointer to the allocators <code>free()</code> function.
    1.59 + * @see UcxAllocator
    1.60 + */
    1.61  typedef void(*ucx_allocator_free)(void *pool, void *data);
    1.62  
    1.63 +/**
    1.64 + * UCX allocator data structure containing memory management functions.
    1.65 + */
    1.66  typedef struct {
    1.67 +    /** Pointer to an area of memory or a complex memory pool.
    1.68 +     * This pointer will be passed to any memory management function as first
    1.69 +     * argument.
    1.70 +     */
    1.71      void *pool;
    1.72 +    /**
    1.73 +     * The <code>malloc()</code> function for this allocator.
    1.74 +     */
    1.75      ucx_allocator_malloc  malloc;
    1.76 +    /**
    1.77 +     * The <code>calloc()</code> function for this allocator.
    1.78 +     */
    1.79      ucx_allocator_calloc  calloc;
    1.80 +    /**
    1.81 +     * The <code>realloc()</code> function for this allocator.
    1.82 +     */
    1.83      ucx_allocator_realloc realloc;
    1.84 +    /**
    1.85 +     * The <code>free()</code> function for this allocator.
    1.86 +     */
    1.87      ucx_allocator_free    free;
    1.88  } UcxAllocator;
    1.89  
    1.90 +/**
    1.91 + * Returns a pointer to the default allocator.
    1.92 + * 
    1.93 + * The default allocator contains wrappers to the standard libc memory
    1.94 + * management functions. Use this function to get a pointer to a globally
    1.95 + * available allocator. You may also define an own UcxAllocator by assigning
    1.96 + * #UCX_ALLOCATOR_DEFAULT to a variable and pass the address of this variable
    1.97 + * to any function that takes an UcxAllocator as argument. Note that using
    1.98 + * this function is the recommended way of passing a default allocator, thus
    1.99 + * it never runs out of scope.
   1.100 + * 
   1.101 + * @return a pointer to the default allocator
   1.102 + * 
   1.103 + * @see UCX_ALLOCATOR_DEFAULT
   1.104 + */
   1.105  UcxAllocator *ucx_default_allocator();
   1.106  
   1.107 +/**
   1.108 + * A wrapper for the standard libc <code>malloc()</code> function.
   1.109 + * @param ignore ignored (may be used by allocators for pooled memory)
   1.110 + * @param n argument passed to <code>malloc()</code>
   1.111 + * @return return value of <code>malloc()</code>
   1.112 + */
   1.113  void *ucx_default_malloc(void *ignore, size_t n);
   1.114 +/**
   1.115 + * A wrapper for the standard libc <code>calloc()</code> function.
   1.116 + * @param ignore ignored (may be used by allocators for pooled memory)
   1.117 + * @param n argument passed to <code>calloc()</code>
   1.118 + * @param size  argument passed to <code>calloc()</code>
   1.119 + * @return return value of <code>calloc()</code>
   1.120 + */
   1.121  void *ucx_default_calloc(void *ignore, size_t n, size_t size);
   1.122 +/**
   1.123 + * A wrapper for the standard libc <code>realloc()</code> function.
   1.124 + * @param ignore ignored (may be used by allocators for pooled memory)
   1.125 + * @param data argumend passed to <code>realloc()</code>
   1.126 + * @param n argument passed to <code>realloc()</code>
   1.127 + * @return return value of <code>realloc()</code>
   1.128 + */
   1.129  void *ucx_default_realloc(void *ignore, void *data, size_t n);
   1.130 +/**
   1.131 + * A wrapper for the standard libc <code>free()</code> function.
   1.132 + * @param ignore ignored (may be used by allocators for pooled memory)
   1.133 + * @param data argument passed to <code>free()</code>
   1.134 + * @return return value of <code>free()</code>
   1.135 + */
   1.136  void ucx_default_free(void *ignore, void *data);
   1.137  
   1.138 +/**
   1.139 + * Convenient macro for a default allocator <code>struct</code> definition.
   1.140 + */
   1.141  #define UCX_ALLOCATOR_DEFAULT {NULL, \
   1.142          ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \
   1.143          ucx_default_free }
   1.144 @@ -63,5 +165,5 @@
   1.145  }
   1.146  #endif
   1.147  
   1.148 -#endif	/* ALLOCATOR_H */
   1.149 +#endif	/* UCX_ALLOCATOR_H */
   1.150  

     2.1 --- a/ucx/string.h	Wed Jul 17 16:17:42 2013 +0200
     2.2 +++ b/ucx/string.h	Wed Jul 17 20:03:01 2013 +0200
     2.3 @@ -183,12 +183,48 @@
     2.4   * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
     2.5   * <code>free()</code>.
     2.6   * 
     2.7 + * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
     2.8 + * terminated.
     2.9 + * 
    2.10   * @param string the string to duplicate
    2.11 - * @return a duplicate of the argument
    2.12 + * @return a duplicate of the string
    2.13   */
    2.14  sstr_t sstrdup(sstr_t string);
    2.15 -sstr_t sstrdupa(UcxAllocator *allocator, sstr_t s);
    2.16  
    2.17 +/**
    2.18 + * Creates a duplicate of the specified string using an UcxAllocator.
    2.19 + * 
    2.20 + * The new sstr_t will contain a copy allocated by the allocators
    2.21 + * ucx_allocator_malloc function. So it is implementation depended, whether the
    2.22 + * returned sstr_t.ptr pointer must be passed to the allocators
    2.23 + * ucx_allocator_free function manually.
    2.24 + * 
    2.25 + * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
    2.26 + * terminated.
    2.27 + * 
    2.28 + * @param allocator a valid instance of an UcxAllocator
    2.29 + * @param string the string to duplicate
    2.30 + * @return a duplicate of the string
    2.31 + */
    2.32 +sstr_t sstrdupa(UcxAllocator *allocator, sstr_t string);
    2.33 +
    2.34 +/**
    2.35 + * Omits leading and trailing spaces.
    2.36 + * 
    2.37 + * This function returns a new sstr_t containing a trimmed version of the
    2.38 + * specified string.
    2.39 + * 
    2.40 + * <b>Note:</b> the new sstr_t references the same memory, thus you
    2.41 + * <b>MUST NOT</b> pass the sstr_t.ptr of the return value to
    2.42 + * <code>free()</code>. It is also highly recommended to avoid assignments like
    2.43 + * <code>mystr = sstrtrim(mystr);</code> as you lose the reference to the
    2.44 + * source string. Assignments of this type are only permitted, if the
    2.45 + * sstr_t.ptr of the source string does not need to be freed or if another
    2.46 + * reference to the source string exists.
    2.47 + * 
    2.48 + * @param string the string that shall be trimmed
    2.49 + * @return a new sstr_t containing the trimmed string
    2.50 + */
    2.51  sstr_t sstrtrim(sstr_t string);
    2.52  
    2.53  #ifdef	__cplusplus