Mercurial > hg > ucx / changeset

     1.1 --- a/src/cx/allocator.h	Sun Sep 26 15:26:43 2021 +0200
     1.2 +++ b/src/cx/allocator.h	Sun Sep 26 16:12:21 2021 +0200
     1.3 @@ -25,6 +25,10 @@
     1.4   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     1.5   * POSSIBILITY OF SUCH DAMAGE.
     1.6   */
     1.7 +/**
     1.8 + * \file allocator.h
     1.9 + * Interface for custom allocators.
    1.10 + */
    1.11  
    1.12  #ifndef UCX_ALLOCATOR_H
    1.13  #define UCX_ALLOCATOR_H
    1.14 @@ -35,29 +39,136 @@
    1.15  extern "C" {
    1.16  #endif
    1.17  
    1.18 +/**
    1.19 + * The class definition for an allocator.
    1.20 + */
    1.21  typedef struct {
    1.22 +    /**
    1.23 +     * Allocate \p n bytes of memory.
    1.24 +     *
    1.25 +     * @param data the allocator's data
    1.26 +     * @param n the number of bytes
    1.27 +     * @return a pointer to the allocated memory
    1.28 +     */
    1.29      void *(*malloc)(void *data, size_t n);
    1.30 +
    1.31 +    /**
    1.32 +     * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
    1.33 +     * This function may return the same pointer that was passed to it, if moving the memory
    1.34 +     * was not necessary.
    1.35 +     *
    1.36 +     * \note Re-allocating a block allocated by a different allocator is undefined.
    1.37 +     *
    1.38 +     * @param data the allocator's data
    1.39 +     * @param mem pointer to the previously allocated block
    1.40 +     * @param n the new size in bytes
    1.41 +     * @return a pointer to the re-allocated memory
    1.42 +     */
    1.43      void *(*realloc)(void *data, void *mem, size_t n);
    1.44 +
    1.45 +    /**
    1.46 +     * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
    1.47 +     *
    1.48 +     * @param data the allocator's data
    1.49 +     * @param nelem the number of elements
    1.50 +     * @param n the size of each element in bytes
    1.51 +     * @return a pointer to the allocated memory
    1.52 +     */
    1.53      void *(*calloc)(void *data, size_t nelem, size_t n);
    1.54 -    void(*free)(void *data, void *mem);
    1.55 +
    1.56 +    /**
    1.57 +     * Free a block allocated by this allocator.
    1.58 +     *
    1.59 +     * \note Freeing a block of a different allocator is undefined.
    1.60 +     *
    1.61 +     * @param data the allocator's data
    1.62 +     * @param mem a pointer to the block to free
    1.63 +     */
    1.64 +    void (*free)(void *data, void *mem);
    1.65  } cx_allocator_class;
    1.66  
    1.67 +/**
    1.68 + * Structure holding the data for an allocator.
    1.69 + */
    1.70  struct cx_allocator_s {
    1.71 +    /**
    1.72 +     * A pointer to the instance of the allocator class.
    1.73 +     */
    1.74      cx_allocator_class *cl;
    1.75 +    /**
    1.76 +     * A pointer to the data this allocator uses.
    1.77 +     */
    1.78      void *data;
    1.79  };
    1.80 +
    1.81 +/**
    1.82 + * High-Level type alias for the allocator type.
    1.83 + */
    1.84  typedef struct cx_allocator_s *CxAllocator;
    1.85  
    1.86 +/**
    1.87 + * A default allocator using standard library malloc() etc.
    1.88 + */
    1.89  extern CxAllocator cxDefaultAllocator;
    1.90  
    1.91 +/**
    1.92 + * Allocate \p n bytes of memory.
    1.93 + *
    1.94 + * @param allocator the allocator
    1.95 + * @param n the number of bytes
    1.96 + * @return a pointer to the allocated memory
    1.97 + */
    1.98  void *cxMalloc(CxAllocator allocator, size_t n);
    1.99  
   1.100 +/**
   1.101 + * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long.
   1.102 + * This function may return the same pointer that was passed to it, if moving the memory
   1.103 + * was not necessary.
   1.104 + *
   1.105 + * \note Re-allocating a block allocated by a different allocator is undefined.
   1.106 + *
   1.107 + * @param allocator the allocator
   1.108 + * @param mem pointer to the previously allocated block
   1.109 + * @param n the new size in bytes
   1.110 + * @return a pointer to the re-allocated memory
   1.111 + */
   1.112  void *cxRealloc(CxAllocator allocator, void *mem, size_t n);
   1.113  
   1.114 +/**
   1.115 + * Re-allocate a previously allocated block and changes the pointer in-place, if necessary.
   1.116 + * This function acts like cxRealloc() using the pointer pointed to by \p mem.
   1.117 + * On success, the pointer is changed to the new location (in case the
   1.118 + *
   1.119 + * \note Re-allocating a block allocated by a different allocator is undefined.
   1.120 + *
   1.121 + * \par Error handling
   1.122 + * \c errno will be set, if the underlying realloc function does so.
   1.123 + *
   1.124 + * @param allocator the allocator
   1.125 + * @param mem pointer to the pointer to allocated block
   1.126 + * @param n the new size in bytes
   1.127 + * @return zero on success, non-zero on failure
   1.128 + */
   1.129  int cxReallocate(CxAllocator allocator, void **mem, size_t n);
   1.130  
   1.131 +/**
   1.132 + * Allocate \p nelem elements of \p n bytes each, all initialized to zero.
   1.133 + *
   1.134 + * @param allocator the allocator
   1.135 + * @param nelem the number of elements
   1.136 + * @param n the size of each element in bytes
   1.137 + * @return a pointer to the allocated memory
   1.138 + */
   1.139  void *cxCalloc(CxAllocator allocator, size_t nelem, size_t n);
   1.140  
   1.141 +/**
   1.142 + * Free a block allocated by this allocator.
   1.143 + *
   1.144 + * \note Freeing a block of a different allocator is undefined.
   1.145 + *
   1.146 + * @param allocator the allocator
   1.147 + * @param mem a pointer to the block to free
   1.148 + */
   1.149  void cxFree(CxAllocator allocator, void *mem);
   1.150  
   1.151  #ifdef __cplusplus