ucx: src/cx/allocator.h@eb9e7bd40a8e

     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)(void *data, size_t n);

    51     /**

    52      * The allocator's realloc() implementation.

    53      */

    54     void *(*realloc)(void *data, void *mem, size_t n)

    55     __attribute__((__warn_unused_result__));

    57     /**

    58      * The allocator's calloc() implementation.

    59      */

    60     void *(*calloc)(void *data, size_t nelem, size_t n);

    62     /**

    63      * The allocator's free() implementation.

    64      */

    65     void (*free)(void *data, void *mem)

    66     __attribute__((__nonnull__));

    67 } cx_allocator_class;

    69 /**

    70  * Structure holding the data for an allocator.

    71  */

    72 struct cx_allocator_s {

    73     /**

    74      * A pointer to the instance of the allocator class.

    75      */

    76     cx_allocator_class *cl;

    77     /**

    78      * A pointer to the data this allocator uses.

    79      */

    80     void *data;

    81 };

    83 /**

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

    85  */

    86 typedef struct cx_allocator_s CxAllocator;

    88 /**

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

    90  */

    91 extern CxAllocator *cxDefaultAllocator;

    93 /**

    94  * Allocate \p n bytes of memory.

    95  *

    96  * @param allocator the allocator

    97  * @param n the number of bytes

    98  * @return a pointer to the allocated memory

    99  */

   100 void *cxMalloc(

   101         CxAllocator *allocator,

   102         size_t n

   103 )

   104 __attribute__((__malloc__))

   105 __attribute__((__alloc_size__(2)));

   107 /**

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

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

   110  * was not necessary.

   111  *

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

   113  *

   114  * @param allocator the allocator

   115  * @param mem pointer to the previously allocated block

   116  * @param n the new size in bytes

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

   118  */

   119 void *cxRealloc(

   120         CxAllocator *allocator,

   121         void *mem,

   122         size_t n

   123 )

   124 __attribute__((__warn_unused_result__))

   125 __attribute__((__alloc_size__(3)));

   127 /**

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

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

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

   131  *

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

   133  *

   134  * \par Error handling

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

   136  *

   137  * @param allocator the allocator

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

   139  * @param n the new size in bytes

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

   141  */

   142 int cxReallocate(

   143         CxAllocator *allocator,

   144         void **mem,

   145         size_t n

   146 )

   147 __attribute__((__nonnull__));

   149 /**

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

   151  *

   152  * @param allocator the allocator

   153  * @param nelem the number of elements

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

   155  * @return a pointer to the allocated memory

   156  */

   157 void *cxCalloc(

   158         CxAllocator *allocator,

   159         size_t nelem,

   160         size_t n

   161 )

   162 __attribute__((__malloc__))

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

   165 /**

   166  * Free a block allocated by this allocator.

   167  *

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

   169  *

   170  * @param allocator the allocator

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

   172  */

   173 void cxFree(

   174         CxAllocator *allocator,

   175         void *mem

   176 )

   177 __attribute__((__nonnull__));

   179 #ifdef __cplusplus

   180 } /* extern "C" */

   181 #endif

   183 #endif /* UCX_ALLOCATOR_H */

Mercurial > hg > ucx / file revision