mempool_funcs.h (9110B)
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_PAR_NONNULL_ (1) 118 mhd_FN_RET_UNALIASED mhd_FN_RET_SIZED (2) 119 mhd_FN_RET_ALIGNED (mhd_MEMPOOL_ALIGN_SIZE); 120 121 /** 122 * Checks whether allocated block is re-sizable in-place. 123 * If block is not re-sizable in-place, it still could be shrunk, but freed 124 * memory will not be re-used until reset of the pool. 125 * @param pool the memory pool to use 126 * @param block the pointer to the allocated block to check 127 * @param block_size the size of the allocated @a block 128 * @return true if block can be resized in-place in the optimal way, 129 * false otherwise 130 */ 131 MHD_INTERNAL bool 132 mhd_pool_is_resizable_inplace (struct mhd_MemoryPool *restrict pool, 133 void *restrict block, 134 size_t block_size) 135 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_IF_NONZERO_ (2, 3); 136 137 /** 138 * Try to allocate @a size bytes memory area from the @a pool. 139 * 140 * If allocation fails, @a required_bytes is updated with size required to be 141 * freed in the @a pool from rellocatable area to allocate requested number 142 * of bytes. 143 * Allocated memory area is always not rellocatable ("from end"). 144 * 145 * @param pool memory pool to use for the operation 146 * @param size the size of memory in bytes to allocate 147 * @param[out] required_bytes the pointer to variable to be updated with 148 * the size of the required additional free 149 * memory area, set to 0 if function succeeds. 150 * Cannot be NULL. 151 * @return the pointer to allocated memory area if succeed, 152 * NULL if the pool doesn't have enough space, required_bytes is updated 153 * with amount of space needed to be freed in rellocatable area or 154 * set to SIZE_MAX if requested size is too large for the pool. 155 */ 156 MHD_INTERNAL void * 157 mhd_pool_try_alloc (struct mhd_MemoryPool *restrict pool, 158 size_t size, 159 size_t *restrict required_bytes) 160 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_ (3) MHD_FN_PAR_OUT_ (3) 161 mhd_FN_RET_UNALIASED mhd_FN_RET_SIZED (2) 162 mhd_FN_RET_ALIGNED (mhd_MEMPOOL_ALIGN_SIZE); 163 164 165 /** 166 * Reallocate a block of memory obtained from the pool. 167 * This is particularly efficient when growing or 168 * shrinking the block that was last (re)allocated. 169 * If the given block is not the most recently 170 * (re)allocated block, the memory of the previous 171 * allocation may be not released until the pool is 172 * destroyed or reset. 173 * 174 * @param pool memory pool to use for the operation 175 * @param old the existing block 176 * @param old_size the size of the existing block 177 * @param new_size the new size of the block 178 * @return new address of the block, or 179 * NULL if the pool cannot support @a new_size 180 * bytes (old continues to be valid for @a old_size) 181 */ 182 MHD_INTERNAL void * 183 mhd_pool_reallocate (struct mhd_MemoryPool *restrict pool, 184 void *restrict old, 185 size_t old_size, 186 size_t new_size) 187 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_IF_NONZERO_ (2, 3) 188 mhd_FN_RET_SIZED (4); 189 190 /** 191 * Get the size of the memory pool 192 * @param pool pool to check 193 * @return the maximum allocation size possible with empty memory pool 194 */ 195 MHD_INTERNAL size_t 196 mhd_pool_get_size (const struct mhd_MemoryPool *restrict pool) 197 MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PURE_; 198 199 /** 200 * Check how much memory is left in the @a pool 201 * 202 * @param pool pool to check 203 * @return number of bytes still available in @a pool 204 */ 205 MHD_INTERNAL size_t 206 mhd_pool_get_free (struct mhd_MemoryPool *restrict pool) 207 MHD_FN_PAR_NONNULL_ (1); 208 209 210 /** 211 * Deallocate a block of memory obtained from the pool. 212 * 213 * If the given block is not the most recently 214 * (re)allocated block, the memory of the this block 215 * allocation may be not released until the pool is 216 * destroyed or reset. 217 * 218 * @param pool memory pool to use for the operation 219 * @param block the allocated block, the NULL is tolerated 220 * @param block_size the size of the allocated block 221 */ 222 MHD_INTERNAL void 223 mhd_pool_deallocate (struct mhd_MemoryPool *restrict pool, 224 void *restrict block, 225 size_t block_size) 226 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_IF_NONZERO_ (2, 3); 227 228 229 /** 230 * Clear all entries from the memory pool except 231 * for @a keep of the given @a copy_bytes. The pointer 232 * returned should be a buffer of @a new_size where 233 * the first @a copy_bytes are from @a keep. 234 * 235 * @param pool memory pool to use for the operation 236 * @param keep pointer to the entry to keep (maybe NULL) 237 * @param copy_bytes how many bytes need to be kept at this address 238 * @param new_size how many bytes should the allocation we return have? 239 * (should be larger or equal to @a copy_bytes) 240 * @return addr new address of @a keep (if it had to change) 241 */ 242 MHD_INTERNAL void * 243 mhd_pool_reset (struct mhd_MemoryPool *restrict pool, 244 void *restrict keep, 245 size_t copy_bytes, 246 size_t new_size) 247 MHD_FN_PAR_NONNULL_ (1) MHD_FN_PAR_NONNULL_IF_NONZERO_ (2, 3) 248 mhd_FN_RET_SIZED (4) mhd_FN_RET_ALIGNED (mhd_MEMPOOL_ALIGN_SIZE); 249 250 #endif /* ! MHD_MEMPOOL_FUNCS_H */