ucx/cx/allocator.h

   1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   3  *
   4  * Copyright 2021 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  * \file allocator.h
  30  * Interface for custom allocators.
  31  */
  32
  33 #ifndef UCX_ALLOCATOR_H
  34 #define UCX_ALLOCATOR_H
  35
  36 #include "common.h"
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 /**
  43  * The class definition for an allocator.
  44  */
  45 typedef struct {
  46     /**
  47      * The allocator's malloc() implementation.
  48      */
  49     void *(*malloc)(
  50             void *data,
  51             size_t n
  52     );
  53
  54     /**
  55      * The allocator's realloc() implementation.
  56      */
  57     void *(*realloc)(
  58             void *data,
  59             void *mem,
  60             size_t n
  61     )
  62     __attribute__((__warn_unused_result__));
  63
  64     /**
  65      * The allocator's calloc() implementation.
  66      */
  67     void *(*calloc)(
  68             void *data,
  69             size_t nelem,
  70             size_t n
  71     );
  72
  73     /**
  74      * The allocator's free() implementation.
  75      */
  76     void (*free)(
  77             void *data,
  78             void *mem
  79     )
  80     __attribute__((__nonnull__));
  81 } cx_allocator_class;
  82
  83 /**
  84  * Structure holding the data for an allocator.
  85  */
  86 struct cx_allocator_s {
  87     /**
  88      * A pointer to the instance of the allocator class.
  89      */
  90     cx_allocator_class *cl;
  91     /**
  92      * A pointer to the data this allocator uses.
  93      */
  94     void *data;
  95 };
  96
  97 /**
  98  * High-Level type alias for the allocator type.
  99  */
 100 typedef struct cx_allocator_s CxAllocator;
 101
 102 /**
 103  * A default allocator using standard library malloc() etc.
 104  */
 105 extern CxAllocator *cxDefaultAllocator;
 106
 107 /**
 108  * Function pointer type for destructor functions.
 109  *
 110  * A destructor function deallocates possible contents and MAY free the memory
 111  * pointed to by \p memory. Read the documentation of the respective function
 112  * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
 113  * particular implementation.
 114  *
 115  * @param memory a pointer to the object to destruct
 116   */
 117 typedef void (*cx_destructor_func)(void *memory) __attribute__((__nonnull__));
 118
 119 /**
 120  * Function pointer type for destructor functions.
 121  *
 122  * A destructor function deallocates possible contents and MAY free the memory
 123  * pointed to by \p memory. Read the documentation of the respective function
 124  * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that
 125  * particular implementation.
 126  *
 127  * @param data an optional pointer to custom data
 128  * @param memory a pointer to the object to destruct
 129   */
 130 typedef void (*cx_destructor_func2)(
 131         void *data,
 132         void *memory
 133 ) __attribute__((__nonnull__(2)));
 134
 135 /**
 136  * Structure holding an advanced destructor function and the desired payload.
 137  * Invocations of func should use data as first argument.
 138  */
 139 typedef struct {
 140     /**
 141      * A pointer to the data that SHALL be used to invoke func.
 142      */
 143     void *data;
 144     /**
 145      * A pointer to the function to invoke.
 146      */
 147     cx_destructor_func2 func;
 148 } cx_advanced_destructor;
 149
 150 /**
 151  * Specifies the type of destructor to use.
 152  */
 153 enum cx_destructor_type {
 154     /**
 155      * Do not use a destructor function.
 156      */
 157     CX_DESTRUCTOR_NONE,
 158     /**
 159      * Use a simple destructor.
 160      * @see cx_destructor_func
 161      */
 162     CX_DESTRUCTOR_SIMPLE,
 163     /**
 164      * Use an advanced destructor.
 165      * @see cx_advanced_destructor
 166      */
 167     CX_DESTRUCTOR_ADVANCED
 168 };
 169
 170 /**
 171  * Allocate \p n bytes of memory.
 172  *
 173  * @param allocator the allocator
 174  * @param n the number of bytes
 175  * @return a pointer to the allocated memory
 176  */
 177 void *cxMalloc(
 178         CxAllocator const *allocator,
 179         size_t n
 180 )
 181 __attribute__((__malloc__))
 182 __attribute__((__alloc_size__(2)));
 183
 184 /**
 185  * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
 186  * This function may return the same pointer that was passed to it, if moving the memory
 187  * was not necessary.
 188  *
 189  * \note Re-allocating a block allocated by a different allocator is undefined.
 190  *
 191  * @param allocator the allocator
 192  * @param mem pointer to the previously allocated block
 193  * @param n the new size in bytes
 194  * @return a pointer to the re-allocated memory
 195  */
 196 void *cxRealloc(
 197         CxAllocator const *allocator,
 198         void *mem,
 199         size_t n
 200 )
 201 __attribute__((__warn_unused_result__))
 202 __attribute__((__alloc_size__(3)));
 203
 204 /**
 205  * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
 206  * This function acts like cxRealloc() using the pointer pointed to by \p mem.
 207  * On success, the pointer is changed to the new location (in case the
 208  *
 209  * \note Re-allocating a block allocated by a different allocator is undefined.
 210  *
 211  * \par Error handling
 212  * \c errno will be set, if the underlying realloc function does so.
 213  *
 214  * @param allocator the allocator
 215  * @param mem pointer to the pointer to allocated block
 216  * @param n the new size in bytes
 217  * @return zero on success, non-zero on failure
 218  */
 219 int cxReallocate(
 220         CxAllocator const *allocator,
 221         void **mem,
 222         size_t n
 223 )
 224 __attribute__((__nonnull__));
 225
 226 /**
 227  * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
 228  *
 229  * @param allocator the allocator
 230  * @param nelem the number of elements
 231  * @param n the size of each element in bytes
 232  * @return a pointer to the allocated memory
 233  */
 234 void *cxCalloc(
 235         CxAllocator const *allocator,
 236         size_t nelem,
 237         size_t n
 238 )
 239 __attribute__((__malloc__))
 240 __attribute__((__alloc_size__(2, 3)));
 241
 242 /**
 243  * Free a block allocated by this allocator.
 244  *
 245  * \note Freeing a block of a different allocator is undefined.
 246  *
 247  * @param allocator the allocator
 248  * @param mem a pointer to the block to free
 249  */
 250 void cxFree(
 251         CxAllocator const *allocator,
 252         void *mem
 253 )
 254 __attribute__((__nonnull__));
 255
 256 #ifdef __cplusplus
 257 } // extern "C"
 258 #endif
 259
 260 #endif // UCX_ALLOCATOR_H