ucx: src/cx/allocator.h@a89857072ace

     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.

   112  *

   113  * @param memory a pointer to the object to destruct

   114  * @return \p memory if it has NOT been free'd by this destructor, otherwise \c NULL

   115   */

   116 typedef void *(*cx_destructor_func)(void *memory)

   117         __attribute__((__nonnull__, __warn_unused_result__));

   119 /**

   120  * Allocate \p n bytes of memory.

   121  *

   122  * @param allocator the allocator

   123  * @param n the number of bytes

   124  * @return a pointer to the allocated memory

   125  */

   126 void *cxMalloc(

   127         CxAllocator *allocator,

   128         size_t n

   129 )

   130 __attribute__((__malloc__))

   131 __attribute__((__alloc_size__(2)));

   133 /**

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

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

   136  * was not necessary.

   137  *

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

   139  *

   140  * @param allocator the allocator

   141  * @param mem pointer to the previously allocated block

   142  * @param n the new size in bytes

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

   144  */

   145 void *cxRealloc(

   146         CxAllocator *allocator,

   147         void *mem,

   148         size_t n

   149 )

   150 __attribute__((__warn_unused_result__))

   151 __attribute__((__alloc_size__(3)));

   153 /**

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

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

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

   157  *

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

   159  *

   160  * \par Error handling

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

   162  *

   163  * @param allocator the allocator

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

   165  * @param n the new size in bytes

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

   167  */

   168 int cxReallocate(

   169         CxAllocator *allocator,

   170         void **mem,

   171         size_t n

   172 )

   173 __attribute__((__nonnull__));

   175 /**

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

   177  *

   178  * @param allocator the allocator

   179  * @param nelem the number of elements

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

   181  * @return a pointer to the allocated memory

   182  */

   183 void *cxCalloc(

   184         CxAllocator *allocator,

   185         size_t nelem,

   186         size_t n

   187 )

   188 __attribute__((__malloc__))

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

   191 /**

   192  * Free a block allocated by this allocator.

   193  *

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

   195  *

   196  * @param allocator the allocator

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

   198  */

   199 void cxFree(

   200         CxAllocator *allocator,

   201         void *mem

   202 )

   203 __attribute__((__nonnull__));

   205 #ifdef __cplusplus

   206 } /* extern "C" */

   207 #endif

   209 #endif /* UCX_ALLOCATOR_H */

Mercurial > hg > ucx / file revision