1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/ucx/mempool.h Tue Oct 17 16:15:41 2017 +0200 1.3 @@ -0,0 +1,200 @@ 1.4 +/* 1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 1.6 + * 1.7 + * Copyright 2017 Olaf Wintermann. All rights reserved. 1.8 + * 1.9 + * Redistribution and use in source and binary forms, with or without 1.10 + * modification, are permitted provided that the following conditions are met: 1.11 + * 1.12 + * 1. Redistributions of source code must retain the above copyright 1.13 + * notice, this list of conditions and the following disclaimer. 1.14 + * 1.15 + * 2. Redistributions in binary form must reproduce the above copyright 1.16 + * notice, this list of conditions and the following disclaimer in the 1.17 + * documentation and/or other materials provided with the distribution. 1.18 + * 1.19 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 1.20 + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1.21 + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 1.22 + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 1.23 + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 1.24 + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 1.25 + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 1.26 + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 1.27 + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 1.28 + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 1.29 + * POSSIBILITY OF SUCH DAMAGE. 1.30 + */ 1.31 + 1.32 +/** 1.33 + * @file mempool.h 1.34 + * 1.35 + * Memory pool implementation. 1.36 + * 1.37 + * @author Mike Becker 1.38 + * @author Olaf Wintermann 1.39 + */ 1.40 + 1.41 +#ifndef UCX_MEMPOOL_H 1.42 +#define UCX_MEMPOOL_H 1.43 + 1.44 +#include <ucx/ucx.h> 1.45 +#include <ucx/allocator.h> 1.46 +#include <stddef.h> 1.47 + 1.48 +#ifdef __cplusplus 1.49 +extern "C" { 1.50 +#endif 1.51 + 1.52 +/** 1.53 + * UCX mempool structure. 1.54 + */ 1.55 +typedef struct { 1.56 + /** UcxAllocator based on this pool */ 1.57 + UcxAllocator *allocator; 1.58 + 1.59 + /** List of pointers to pooled memory. */ 1.60 + void **data; 1.61 + 1.62 + /** Count of pooled memory items. */ 1.63 + size_t ndata; 1.64 + 1.65 + /** Memory pool size. */ 1.66 + size_t size; 1.67 +} UcxMempool; 1.68 + 1.69 +/** Shorthand for a new default memory pool with a capacity of 16 elements. */ 1.70 +#define ucx_mempool_new_default() ucx_mempool_new(16) 1.71 + 1.72 + 1.73 +/** 1.74 + * Creates a memory pool with the specified initial size. 1.75 + * 1.76 + * As the created memory pool automatically grows in size by factor two when 1.77 + * trying to allocate memory on a full pool, it is recommended that you use 1.78 + * a power of two for the initial size. 1.79 + * 1.80 + * @param n initial pool size (should be a power of two, e.g. 16) 1.81 + * @return a pointer to the new memory pool 1.82 + * @see ucx_mempool_new_default() 1.83 + */ 1.84 +UcxMempool *ucx_mempool_new(size_t n); 1.85 + 1.86 +/** 1.87 + * Resizes a memory pool. 1.88 + * 1.89 + * This function will fail if the new capacity is not sufficient for the 1.90 + * present data. 1.91 + * 1.92 + * @param pool the pool to resize 1.93 + * @param newcap the new capacity 1.94 + * @return zero on success or non-zero on failure 1.95 + */ 1.96 +int ucx_mempool_chcap(UcxMempool *pool, size_t newcap); 1.97 + 1.98 +/** 1.99 + * Allocates pooled memory. 1.100 + * 1.101 + * @param pool the memory pool 1.102 + * @param n amount of memory to allocate 1.103 + * @return a pointer to the allocated memory 1.104 + * @see ucx_allocator_malloc() 1.105 + */ 1.106 +void *ucx_mempool_malloc(UcxMempool *pool, size_t n); 1.107 +/** 1.108 + * Allocates a pooled memory array. 1.109 + * 1.110 + * The content of the allocated memory is set to zero. 1.111 + * 1.112 + * @param pool the memory pool 1.113 + * @param nelem amount of elements to allocate 1.114 + * @param elsize amount of memory per element 1.115 + * @return a pointer to the allocated memory 1.116 + * @see ucx_allocator_calloc() 1.117 + */ 1.118 +void *ucx_mempool_calloc(UcxMempool *pool, size_t nelem, size_t elsize); 1.119 + 1.120 +/** 1.121 + * Reallocates pooled memory. 1.122 + * 1.123 + * If the memory to be reallocated is not contained by the specified pool, the 1.124 + * behavior is undefined. 1.125 + * 1.126 + * @param pool the memory pool 1.127 + * @param ptr a pointer to the memory that shall be reallocated 1.128 + * @param n the new size of the memory 1.129 + * @return a pointer to the new location of the memory 1.130 + * @see ucx_allocator_realloc() 1.131 + */ 1.132 +void *ucx_mempool_realloc(UcxMempool *pool, void *ptr, size_t n); 1.133 + 1.134 +/** 1.135 + * Frees pooled memory. 1.136 + * 1.137 + * Before freeing the memory, the specified destructor function (if any) 1.138 + * is called. 1.139 + * 1.140 + * If you specify memory, that is not pooled by the specified memory pool, the 1.141 + * program will terminate with a call to <code>abort()</code>. 1.142 + * 1.143 + * @param pool the memory pool 1.144 + * @param ptr a pointer to the memory that shall be freed 1.145 + * @see ucx_mempool_set_destr() 1.146 + */ 1.147 +void ucx_mempool_free(UcxMempool *pool, void *ptr); 1.148 + 1.149 +/** 1.150 + * Destroys a memory pool. 1.151 + * 1.152 + * For each element the destructor function (if any) is called and the element 1.153 + * is freed. 1.154 + * 1.155 + * Each of the registered destructor function that has no corresponding element 1.156 + * within the pool (namely those registered by ucx_mempool_reg_destr) is 1.157 + * called interleaving with the element destruction, but with guarantee to the 1.158 + * order in which they were registered (FIFO order). 1.159 + * 1.160 + * 1.161 + * @param pool the mempool to destroy 1.162 + */ 1.163 +void ucx_mempool_destroy(UcxMempool *pool); 1.164 + 1.165 +/** 1.166 + * Sets a destructor function for the specified memory. 1.167 + * 1.168 + * The destructor is automatically called when the memory is freed or the 1.169 + * pool is destroyed. 1.170 + * 1.171 + * The only requirement for the specified memory is, that it <b>MUST</b> be 1.172 + * pooled memory by a UcxMempool or an element-compatible mempool. The pointer 1.173 + * to the destructor function is saved in a reserved area before the actual 1.174 + * memory. 1.175 + * 1.176 + * @param ptr pooled memory 1.177 + * @param func a pointer to the destructor function 1.178 + * @see ucx_mempool_free() 1.179 + * @see ucx_mempool_destroy() 1.180 + */ 1.181 +void ucx_mempool_set_destr(void *ptr, ucx_destructor func); 1.182 + 1.183 +/** 1.184 + * Registers a destructor function for the specified (non-pooled) memory. 1.185 + * 1.186 + * This is useful, if you have memory that has not been allocated by a mempool, 1.187 + * but shall be managed by a mempool. 1.188 + * 1.189 + * This function creates an entry in the specified mempool and the memory will 1.190 + * therefore (logically) convert to pooled memory. 1.191 + * 1.192 + * @param pool the memory pool 1.193 + * @param ptr data the destructor is registered for 1.194 + * @param destr a pointer to the destructor function 1.195 + */ 1.196 +void ucx_mempool_reg_destr(UcxMempool *pool, void *ptr, ucx_destructor destr); 1.197 + 1.198 +#ifdef __cplusplus 1.199 +} 1.200 +#endif 1.201 + 1.202 +#endif /* UCX_MEMPOOL_H */ 1.203 +