ucx/cx/mempool.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 mempool.h
  30  * \brief Interface for memory pool implementations.
  31  * \author Mike Becker
  32  * \author Olaf Wintermann
  33  * \version 3.0
  34  * \copyright 2-Clause BSD License
  35  */
  36
  37 #ifndef UCX_MEMPOOL_H
  38 #define UCX_MEMPOOL_H
  39
  40 #include "common.h"
  41 #include "allocator.h"
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /** Internal structure for pooled memory. */
  48 struct cx_mempool_memory_s;
  49
  50 /**
  51  * The basic structure of a memory pool.
  52  * Should be the first member of an actual memory pool implementation.
  53  */
  54 struct cx_mempool_s {
  55     /** The provided allocator. */
  56     CxAllocator const *allocator;
  57
  58     /**
  59      * A destructor that shall be automatically registered for newly allocated memory.
  60      * This destructor MUST NOT free the memory.
  61      */
  62     cx_destructor_func auto_destr;
  63
  64     /** Array of pooled memory. */
  65     struct cx_mempool_memory_s **data;
  66
  67     /** Number of pooled memory items. */
  68     size_t size;
  69
  70     /** Memory pool capacity. */
  71     size_t capacity;
  72 };
  73
  74 /**
  75  * Common type for all memory pool implementations.
  76  */
  77 typedef struct cx_mempool_s CxMempool;
  78
  79 /**
  80  * Creates an array-based memory pool with a shared destructor function.
  81  *
  82  * This destructor MUST NOT free the memory.
  83  *
  84  * @param capacity the initial capacity of the pool
  85  * @param destr the destructor function to use for allocated memory
  86  * @return the created memory pool or \c NULL if allocation failed
  87  */
  88 __attribute__((__warn_unused_result__))
  89 CxMempool *cxMempoolCreate(size_t capacity, cx_destructor_func destr);
  90
  91 /**
  92  * Creates a basic array-based memory pool.
  93  *
  94  * @param capacity the initial capacity of the pool
  95  * @return the created memory pool or \c NULL if allocation failed
  96  */
  97 __attribute__((__warn_unused_result__))
  98 static inline CxMempool *cxBasicMempoolCreate(size_t capacity) {
  99     return cxMempoolCreate(capacity, NULL);
 100 }
 101
 102 /**
 103  * Destroys a memory pool and frees the managed memory.
 104  *
 105  * @param pool the memory pool to destroy
 106  */
 107 __attribute__((__nonnull__))
 108 void cxMempoolDestroy(CxMempool *pool);
 109
 110 /**
 111  * Sets the destructor function for a specific allocated memory object.
 112  *
 113  * If the memory is not managed by a UCX memory pool, the behavior is undefined.
 114  * The destructor MUST NOT free the memory.
 115  *
 116  * @param memory the object allocated in the pool
 117  * @param fnc the destructor function
 118  */
 119 __attribute__((__nonnull__))
 120 void cxMempoolSetDestructor(
 121         void *memory,
 122         cx_destructor_func fnc
 123 );
 124
 125 /**
 126  * Registers foreign memory with this pool.
 127  *
 128  * The destructor, in contrast to memory allocated by the pool, MUST free the memory.
 129  *
 130  * A small portion of memory will be allocated to register the information in the pool.
 131  * If that allocation fails, this function will return non-zero.
 132  *
 133  * @param pool the pool
 134  * @param memory the object allocated in the pool
 135  * @param destr the destructor function
 136  * @return zero on success, non-zero on failure
 137  */
 138 __attribute__((__nonnull__))
 139 int cxMempoolRegister(
 140         CxMempool *pool,
 141         void *memory,
 142         cx_destructor_func destr
 143 );
 144
 145 #ifdef __cplusplus
 146 } // extern "C"
 147 #endif
 148
 149 #endif // UCX_MEMPOOL_H