ucx: src/cx/allocator.h@35f06c5eeb0e

     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  */

    33 #ifndef UCX_ALLOCATOR_H

    34 #define UCX_ALLOCATOR_H

    36 #include "common.h"

    38 #ifdef __cplusplus

    39 extern "C" {

    40 #endif

    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     );

    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__));

    64     /**

    65      * The allocator's calloc() implementation.

    66      */

    67     void *(*calloc)(

    68             void *data,

    69             size_t nelem,

    70             size_t n

    71     );

    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;

    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 };

    97 /**

    98  * High-Level type alias for the allocator type.

    99  */

   100 typedef struct cx_allocator_s CxAllocator;

   102 /**

   103  * A default allocator using standard library malloc() etc.

   104  */

   105 extern CxAllocator *cxDefaultAllocator;

   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__));

   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)));

   135 /**

   136  * Allocate \p n bytes of memory.

   137  *

   138  * @param allocator the allocator

   139  * @param n the number of bytes

   140  * @return a pointer to the allocated memory

   141  */

   142 void *cxMalloc(

   143         CxAllocator const *allocator,

   144         size_t n

   145 )

   146 __attribute__((__malloc__))

   147 __attribute__((__alloc_size__(2)));

   149 /**

   150  * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.

   151  * This function may return the same pointer that was passed to it, if moving the memory

   152  * was not necessary.

   153  *

   154  * \note Re-allocating a block allocated by a different allocator is undefined.

   155  *

   156  * @param allocator the allocator

   157  * @param mem pointer to the previously allocated block

   158  * @param n the new size in bytes

   159  * @return a pointer to the re-allocated memory

   160  */

   161 void *cxRealloc(

   162         CxAllocator const *allocator,

   163         void *mem,

   164         size_t n

   165 )

   166 __attribute__((__warn_unused_result__))

   167 __attribute__((__alloc_size__(3)));

   169 /**

   170  * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.

   171  * This function acts like cxRealloc() using the pointer pointed to by \p mem.

   172  * On success, the pointer is changed to the new location (in case the

   173  *

   174  * \note Re-allocating a block allocated by a different allocator is undefined.

   175  *

   176  * \par Error handling

   177  * \c errno will be set, if the underlying realloc function does so.

   178  *

   179  * @param allocator the allocator

   180  * @param mem pointer to the pointer to allocated block

   181  * @param n the new size in bytes

   182  * @return zero on success, non-zero on failure

   183  */

   184 int cxReallocate(

   185         CxAllocator const *allocator,

   186         void **mem,

   187         size_t n

   188 )

   189 __attribute__((__nonnull__));

   191 /**

   192  * Allocate \p nelem elements of \p n bytes each, all initialized to zero.

   193  *

   194  * @param allocator the allocator

   195  * @param nelem the number of elements

   196  * @param n the size of each element in bytes

   197  * @return a pointer to the allocated memory

   198  */

   199 void *cxCalloc(

   200         CxAllocator const *allocator,

   201         size_t nelem,

   202         size_t n

   203 )

   204 __attribute__((__malloc__))

   205 __attribute__((__alloc_size__(2, 3)));

   207 /**

   208  * Free a block allocated by this allocator.

   209  *

   210  * \note Freeing a block of a different allocator is undefined.

   211  *

   212  * @param allocator the allocator

   213  * @param mem a pointer to the block to free

   214  */

   215 void cxFree(

   216         CxAllocator const *allocator,

   217         void *mem

   218 )

   219 __attribute__((__nonnull__));

   221 #ifdef __cplusplus

   222 } // extern "C"

   223 #endif

   225 #endif // UCX_ALLOCATOR_H

Mercurial > hg > ucx / file revision