mempool_funcs.h (8790B)
1 /* SPDX-License-Identifier: LGPL-2.1-or-later OR (GPL-2.0-or-later WITH eCos-exception-2.0) */ 2 /* 3 This file is part of GNU libmicrohttpd. 4 Copyright (C) 2007--2024 Daniel Pittman and Christian Grothoff 5 Copyright (C) 2016--2025 Evgeny Grin (Karlson2k) 6 7 GNU libmicrohttpd is free software; you can redistribute it and/or 8 modify it under the terms of the GNU Lesser General Public 9 License as published by the Free Software Foundation; either 10 version 2.1 of the License, or (at your option) any later version. 11 12 GNU libmicrohttpd is distributed in the hope that it will be useful, 13 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 Lesser General Public License for more details. 16 17 Alternatively, you can redistribute GNU libmicrohttpd and/or 18 modify it under the terms of the GNU General Public License as 19 published by the Free Software Foundation; either version 2 of 20 the License, or (at your option) any later version, together 21 with the eCos exception, as follows: 22 23 As a special exception, if other files instantiate templates or 24 use macros or inline functions from this file, or you compile this 25 file and link it with other works to produce a work based on this 26 file, this file does not by itself cause the resulting work to be 27 covered by the GNU General Public License. However the source code 28 for this file must still be made available in accordance with 29 section (3) of the GNU General Public License v2. 30 31 This exception does not invalidate any other reasons why a work 32 based on this file might be covered by the GNU General Public 33 License. 34 35 You should have received copies of the GNU Lesser General Public 36 License and the GNU General Public License along with this library; 37 if not, see <https://www.gnu.org/licenses/>. 38 */ 39 40 /** 41 * @file src/mhd2/mempool_funcs.h 42 * @brief memory pool; mostly used for efficient (de)allocation 43 * for each connection and bounding memory use for each 44 * request 45 * @author Christian Grothoff 46 * @author Karlson2k (Evgeny Grin) 47 */ 48 49 #ifndef MHD_MEMPOOL_FUNCS_H 50 #define MHD_MEMPOOL_FUNCS_H 1 51 52 #include "mhd_sys_options.h" 53 #include "sys_base_types.h" 54 #include "sys_bool_type.h" 55 #include "mempool_types.h" 56 57 58 #ifdef __BIGGEST_ALIGNMENT__ 59 /** 60 * Alignment size used by memory pool function. 61 */ 62 # define mhd_MEMPOOL_ALIGN_SIZE __BIGGEST_ALIGNMENT__ 63 #else /* ! __BIGGEST_ALIGNMENT__ */ 64 /** 65 * Alignment size used by memory pool function. 66 * This is 2x pointer size (similar to GNU libc). 67 */ 68 # define mhd_MEMPOOL_ALIGN_SIZE (2 * sizeof(void*)) 69 #endif /* ! __BIGGEST_ALIGNMENT__ */ 70 71 /** 72 * Perform one-time initialisation of the internal values required for 73 * memory pools functions 74 */ 75 void 76 mhd_init_mem_pools (void); 77 78 79 /** 80 * Destroy a memory pool. 81 * 82 * @param pool memory pool to destroy 83 */ 84 MHD_INTERNAL void 85 mhd_pool_destroy (struct mhd_MemoryPool *restrict pool); 86 87 88 /** 89 * Create a memory pool. 90 * 91 * @param max maximum size of the pool 92 * @param zeroing the request zeroing of allocated and deallocated memory 93 * @return pointer to the new object on success, 94 * NULL on error 95 */ 96 MHD_INTERNAL struct mhd_MemoryPool * 97 mhd_pool_create (size_t max, 98 enum mhd_MemPoolZeroing zeroing) 99 mhd_FN_RET_UNALIASED mhd_FN_OBJ_CONSTRUCTOR (mhd_pool_destroy); 100 101 102 /** 103 * Allocate size bytes from the pool. 104 * 105 * @param pool memory pool to use for the operation 106 * @param size number of bytes to allocate 107 * @param from_end allocate from end of pool (set to 'true'); 108 * use this for small, persistent allocations that 109 * will not be reallocated until pool reset 110 * @return pointer to the new allocated memory region on success, 111 * NULL if the pool does not have enough free memory. 112 */ 113 MHD_INTERNAL void * 114 mhd_pool_allocate (struct mhd_MemoryPool *restrict pool, 115 size_t size, 116 bool from_end) 117 mhd_FN_RET_UNALIASED mhd_FN_RET_SIZED (2) 118 mhd_FN_RET_ALIGNED (mhd_MEMPOOL_ALIGN_SIZE); 119 120 /** 121 * Checks whether allocated block is re-sizable in-place. 122 * If block is not re-sizable in-place, it still could be shrunk, but freed 123 * memory will not be re-used until reset of the pool. 124 * @param pool the memory pool to use 125 * @param block the pointer to the allocated block to check 126 * @param block_size the size of the allocated @a block 127 * @return true if block can be resized in-place in the optimal way, 128 * false otherwise 129 */ 130 MHD_INTERNAL bool 131 mhd_pool_is_resizable_inplace (struct mhd_MemoryPool *restrict pool, 132 void *restrict block, 133 size_t block_size); 134 135 /** 136 * Try to allocate @a size bytes memory area from the @a pool. 137 * 138 * If allocation fails, @a required_bytes is updated with size required to be 139 * freed in the @a pool from rellocatable area to allocate requested number 140 * of bytes. 141 * Allocated memory area is always not rellocatable ("from end"). 142 * 143 * @param pool memory pool to use for the operation 144 * @param size the size of memory in bytes to allocate 145 * @param[out] required_bytes the pointer to variable to be updated with 146 * the size of the required additional free 147 * memory area, set to 0 if function succeeds. 148 * Cannot be NULL. 149 * @return the pointer to allocated memory area if succeed, 150 * NULL if the pool doesn't have enough space, required_bytes is updated 151 * with amount of space needed to be freed in rellocatable area or 152 * set to SIZE_MAX if requested size is too large for the pool. 153 */ 154 MHD_INTERNAL void * 155 mhd_pool_try_alloc (struct mhd_MemoryPool *restrict pool, 156 size_t size, 157 size_t *restrict required_bytes) 158 mhd_FN_RET_UNALIASED mhd_FN_RET_SIZED (2) 159 mhd_FN_RET_ALIGNED (mhd_MEMPOOL_ALIGN_SIZE); 160 161 162 /** 163 * Reallocate a block of memory obtained from the pool. 164 * This is particularly efficient when growing or 165 * shrinking the block that was last (re)allocated. 166 * If the given block is not the most recently 167 * (re)allocated block, the memory of the previous 168 * allocation may be not released until the pool is 169 * destroyed or reset. 170 * 171 * @param pool memory pool to use for the operation 172 * @param old the existing block 173 * @param old_size the size of the existing block 174 * @param new_size the new size of the block 175 * @return new address of the block, or 176 * NULL if the pool cannot support @a new_size 177 * bytes (old continues to be valid for @a old_size) 178 */ 179 MHD_INTERNAL void * 180 mhd_pool_reallocate (struct mhd_MemoryPool *restrict pool, 181 void *restrict old, 182 size_t old_size, 183 size_t new_size) 184 mhd_FN_RET_SIZED (4) mhd_FN_RET_ALIGNED (mhd_MEMPOOL_ALIGN_SIZE); 185 186 /** 187 * Get the size of the memory pool 188 * @param pool pool to check 189 * @return the maximum allocation size possible with empty memory pool 190 */ 191 MHD_INTERNAL size_t 192 mhd_pool_get_size (const struct mhd_MemoryPool *restrict pool) 193 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PURE_; 194 195 /** 196 * Check how much memory is left in the @a pool 197 * 198 * @param pool pool to check 199 * @return number of bytes still available in @a pool 200 */ 201 MHD_INTERNAL size_t 202 mhd_pool_get_free (struct mhd_MemoryPool *restrict pool); 203 204 205 /** 206 * Deallocate a block of memory obtained from the pool. 207 * 208 * If the given block is not the most recently 209 * (re)allocated block, the memory of the this block 210 * allocation may be not released until the pool is 211 * destroyed or reset. 212 * 213 * @param pool memory pool to use for the operation 214 * @param block the allocated block, the NULL is tolerated 215 * @param block_size the size of the allocated block 216 */ 217 MHD_INTERNAL void 218 mhd_pool_deallocate (struct mhd_MemoryPool *restrict pool, 219 void *restrict block, 220 size_t block_size); 221 222 223 /** 224 * Clear all entries from the memory pool except 225 * for @a keep of the given @a copy_bytes. The pointer 226 * returned should be a buffer of @a new_size where 227 * the first @a copy_bytes are from @a keep. 228 * 229 * @param pool memory pool to use for the operation 230 * @param keep pointer to the entry to keep (maybe NULL) 231 * @param copy_bytes how many bytes need to be kept at this address 232 * @param new_size how many bytes should the allocation we return have? 233 * (should be larger or equal to @a copy_bytes) 234 * @return addr new address of @a keep (if it had to change) 235 */ 236 MHD_INTERNAL void * 237 mhd_pool_reset (struct mhd_MemoryPool *restrict pool, 238 void *restrict keep, 239 size_t copy_bytes, 240 size_t new_size) 241 mhd_FN_RET_SIZED (4) mhd_FN_RET_ALIGNED (mhd_MEMPOOL_ALIGN_SIZE); 242 243 #endif /* ! MHD_MEMPOOL_FUNCS_H */