ucx/ucx/allocator.h

   1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   3  *
   4  * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions are met:
   8  *
   9  *   1. Redistributions of source code must retain the above copyright
  10  *      notice, this list of conditions and the following disclaimer.
  11  *
  12  *   2. Redistributions in binary form must reproduce the above copyright
  13  *      notice, this list of conditions and the following disclaimer in the
  14  *      documentation and/or other materials provided with the distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  * POSSIBILITY OF SUCH DAMAGE.
  27  */
  28 /**
  29  * Allocator for custom memory management.
  30  *
  31  * A UCX allocator consists of a pointer to the memory area / pool and four
  32  * function pointers to memory management functions operating on this memory
  33  * area / pool. These functions shall behave equivalent to the standard libc
  34  * functions <code>malloc(), calloc(), realloc()</code> and <code>free()</code>.
  35  *
  36  * The signature of the memory management functions is based on the signature
  37  * of the respective libc function but each of them takes the pointer to the
  38  * memory area / pool as first argument.
  39  *
  40  * As the pointer to the memory area / pool can be arbitrarily chosen, any data
  41  * can be provided to the memory management functions. A UcxMempool is just
  42  * one example.
  43  *
  44  * @see mempool.h
  45  * @see UcxMap
  46  *
  47  * @file   allocator.h
  48  * @author Mike Becker
  49  * @author Olaf Wintermann
  50  */
  51
  52 #ifndef UCX_ALLOCATOR_H
  53 #define UCX_ALLOCATOR_H
  54
  55 #include "ucx.h"
  56
  57 #ifdef  __cplusplus
  58 extern "C" {
  59 #endif
  60
  61 /**
  62  * A function pointer to the allocators <code>malloc()</code> function.
  63  * @see UcxAllocator
  64  */
  65 typedef void*(*ucx_allocator_malloc)(void *pool, size_t n);
  66
  67 /**
  68  * A function pointer to the allocators <code>calloc()</code> function.
  69  * @see UcxAllocator
  70  */
  71 typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size);
  72
  73 /**
  74  * A function pointer to the allocators <code>realloc()</code> function.
  75  * @see UcxAllocator
  76  */
  77 typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n);
  78
  79 /**
  80  * A function pointer to the allocators <code>free()</code> function.
  81  * @see UcxAllocator
  82  */
  83 typedef void(*ucx_allocator_free)(void *pool, void *data);
  84
  85 /**
  86  * UCX allocator data structure containing memory management functions.
  87  */
  88 typedef struct {
  89     /** Pointer to an area of memory or a complex memory pool.
  90      * This pointer will be passed to any memory management function as first
  91      * argument.
  92      */
  93     void *pool;
  94     /**
  95      * The <code>malloc()</code> function for this allocator.
  96      */
  97     ucx_allocator_malloc  malloc;
  98     /**
  99      * The <code>calloc()</code> function for this allocator.
 100      */
 101     ucx_allocator_calloc  calloc;
 102     /**
 103      * The <code>realloc()</code> function for this allocator.
 104      */
 105     ucx_allocator_realloc realloc;
 106     /**
 107      * The <code>free()</code> function for this allocator.
 108      */
 109     ucx_allocator_free    free;
 110 } UcxAllocator;
 111
 112 /**
 113  * Returns a pointer to the default allocator.
 114  *
 115  * The default allocator contains wrappers to the standard libc memory
 116  * management functions. Use this function to get a pointer to a globally
 117  * available allocator. You may also define an own UcxAllocator by assigning
 118  * #UCX_ALLOCATOR_DEFAULT to a variable and pass the address of this variable
 119  * to any function that takes a UcxAllocator as argument. Note that using
 120  * this function is the recommended way of passing a default allocator, thus
 121  * it never runs out of scope.
 122  *
 123  * @return a pointer to the default allocator
 124  *
 125  * @see UCX_ALLOCATOR_DEFAULT
 126  */
 127 UcxAllocator *ucx_default_allocator();
 128
 129 /**
 130  * A wrapper for the standard libc <code>malloc()</code> function.
 131  * @param ignore ignored (may be used by allocators for pooled memory)
 132  * @param n argument passed to <code>malloc()</code>
 133  * @return return value of <code>malloc()</code>
 134  */
 135 void *ucx_default_malloc(void *ignore, size_t n);
 136 /**
 137  * A wrapper for the standard libc <code>calloc()</code> function.
 138  * @param ignore ignored (may be used by allocators for pooled memory)
 139  * @param n argument passed to <code>calloc()</code>
 140  * @param size  argument passed to <code>calloc()</code>
 141  * @return return value of <code>calloc()</code>
 142  */
 143 void *ucx_default_calloc(void *ignore, size_t n, size_t size);
 144 /**
 145  * A wrapper for the standard libc <code>realloc()</code> function.
 146  * @param ignore ignored (may be used by allocators for pooled memory)
 147  * @param data argumend passed to <code>realloc()</code>
 148  * @param n argument passed to <code>realloc()</code>
 149  * @return return value of <code>realloc()</code>
 150  */
 151 void *ucx_default_realloc(void *ignore, void *data, size_t n);
 152 /**
 153  * A wrapper for the standard libc <code>free()</code> function.
 154  * @param ignore ignored (may be used by allocators for pooled memory)
 155  * @param data argument passed to <code>free()</code>
 156  */
 157 void ucx_default_free(void *ignore, void *data);
 158
 159 /**
 160  * Shorthand for calling an allocators malloc function.
 161  * @param allocator the allocator to use
 162  * @param n size of space to allocate
 163  * @return a pointer to the allocated memory area
 164  */
 165 #define almalloc(allocator, n) ((allocator)->malloc((allocator)->pool, n))
 166
 167 /**
 168  * Shorthand for calling an allocators calloc function.
 169  * @param allocator the allocator to use
 170  * @param n the count of elements the space should be allocated for
 171  * @param size the size of each element
 172  * @return a pointer to the allocated memory area
 173  */
 174 #define alcalloc(allocator, n, size) \
 175         ((allocator)->calloc((allocator)->pool, n, size))
 176
 177 /**
 178  * Shorthand for calling an allocators realloc function.
 179  * @param allocator the allocator to use
 180  * @param ptr the pointer to the memory area that shall be reallocated
 181  * @param n the new size of the allocated memory area
 182  * @return a pointer to the reallocated memory area
 183  */
 184 #define alrealloc(allocator, ptr, n) \
 185         ((allocator)->realloc((allocator)->pool, ptr, n))
 186
 187 /**
 188  * Shorthand for calling an allocators free function.
 189  * @param allocator the allocator to use
 190  * @param ptr the pointer to the memory area that shall be freed
 191  */
 192 #define alfree(allocator, ptr) ((allocator)->free((allocator)->pool, ptr))
 193
 194 /**
 195  * Convenient macro for a default allocator <code>struct</code> definition.
 196  */
 197 #define UCX_ALLOCATOR_DEFAULT {NULL, \
 198         ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \
 199         ucx_default_free }
 200
 201 #ifdef  __cplusplus
 202 }
 203 #endif
 204
 205 #endif  /* UCX_ALLOCATOR_H */
 206