comparison: ucx/cx/allocator.h
ucx/cx/allocator.h
- changeset 11
- 0aa8cbd7912e
- parent 0
- 1a157da63d7c
- child 16
- 04c9f8d8f03b
equal
deleted
inserted
replaced
| 10:80f9d007cb52 | 11:0aa8cbd7912e |
|---|---|
| 44 */ | 44 */ |
| 45 typedef struct { | 45 typedef struct { |
| 46 /** | 46 /** |
| 47 * The allocator's malloc() implementation. | 47 * The allocator's malloc() implementation. |
| 48 */ | 48 */ |
| 49 cx_attr_nonnull | |
| 50 cx_attr_nodiscard cx_attr_allocsize(2) | |
| 49 void *(*malloc)( | 51 void *(*malloc)( |
| 50 void *data, | 52 void *data, |
| 51 size_t n | 53 size_t n |
| 52 ); | 54 ); |
| 53 | 55 |
| 54 /** | 56 /** |
| 55 * The allocator's realloc() implementation. | 57 * The allocator's realloc() implementation. |
| 56 */ | 58 */ |
| 59 cx_attr_nodiscard | |
| 60 cx_attr_allocsize(3) | |
| 57 void *(*realloc)( | 61 void *(*realloc)( |
| 58 void *data, | 62 void *data, |
| 59 void *mem, | 63 void *mem, |
| 60 size_t n | 64 size_t n |
| 61 ) | 65 ); |
| 62 __attribute__((__warn_unused_result__)); | |
| 63 | 66 |
| 64 /** | 67 /** |
| 65 * The allocator's calloc() implementation. | 68 * The allocator's calloc() implementation. |
| 66 */ | 69 */ |
| 70 cx_attr_nodiscard | |
| 71 cx_attr_allocsize(2, 3) | |
| 67 void *(*calloc)( | 72 void *(*calloc)( |
| 68 void *data, | 73 void *data, |
| 69 size_t nelem, | 74 size_t nelem, |
| 70 size_t n | 75 size_t n |
| 71 ); | 76 ); |
| 72 | 77 |
| 73 /** | 78 /** |
| 74 * The allocator's free() implementation. | 79 * The allocator's free() implementation. |
| 75 */ | 80 */ |
| 81 cx_attr_nonnull_arg(1) | |
| 76 void (*free)( | 82 void (*free)( |
| 77 void *data, | 83 void *data, |
| 78 void *mem | 84 void *mem |
| 79 ) | 85 ); |
| 80 __attribute__((__nonnull__)); | |
| 81 } cx_allocator_class; | 86 } cx_allocator_class; |
| 82 | 87 |
| 83 /** | 88 /** |
| 84 * Structure holding the data for an allocator. | 89 * Structure holding the data for an allocator. |
| 85 */ | 90 */ |
| 107 /** | 112 /** |
| 108 * Function pointer type for destructor functions. | 113 * Function pointer type for destructor functions. |
| 109 * | 114 * |
| 110 * A destructor function deallocates possible contents and MAY free the memory | 115 * A destructor function deallocates possible contents and MAY free the memory |
| 111 * pointed to by \p memory. Read the documentation of the respective function | 116 * pointed to by \p memory. Read the documentation of the respective function |
| 112 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that | 117 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in |
| 113 * particular implementation. | 118 * that particular implementation. |
| 114 * | 119 * |
| 115 * @param memory a pointer to the object to destruct | 120 * @param memory a pointer to the object to destruct |
| 116 */ | 121 */ |
| 117 typedef void (*cx_destructor_func)(void *memory) __attribute__((__nonnull__)); | 122 typedef void (*cx_destructor_func)(void *memory); |
| 118 | 123 |
| 119 /** | 124 /** |
| 120 * Function pointer type for destructor functions. | 125 * Function pointer type for destructor functions. |
| 121 * | 126 * |
| 122 * A destructor function deallocates possible contents and MAY free the memory | 127 * A destructor function deallocates possible contents and MAY free the memory |
| 123 * pointed to by \p memory. Read the documentation of the respective function | 128 * pointed to by \p memory. Read the documentation of the respective function |
| 124 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in that | 129 * pointer to learn if a destructor SHALL, MAY, or MUST NOT free the memory in |
| 125 * particular implementation. | 130 * that particular implementation. |
| 126 * | 131 * |
| 127 * @param data an optional pointer to custom data | 132 * @param data an optional pointer to custom data |
| 128 * @param memory a pointer to the object to destruct | 133 * @param memory a pointer to the object to destruct |
| 129 */ | 134 */ |
| 130 typedef void (*cx_destructor_func2)( | 135 typedef void (*cx_destructor_func2)( |
| 131 void *data, | 136 void *data, |
| 132 void *memory | 137 void *memory |
| 133 ) __attribute__((__nonnull__(2))); | 138 ); |
| 134 | 139 |
| 135 /** | 140 /** |
| 136 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary. | 141 * Re-allocate a previously allocated block and changes the pointer in-place, |
| 142 * if necessary. | |
| 137 * | 143 * |
| 138 * \par Error handling | 144 * \par Error handling |
| 139 * \c errno will be set by realloc() on failure. | 145 * \c errno will be set by realloc() on failure. |
| 140 * | 146 * |
| 141 * @param mem pointer to the pointer to allocated block | 147 * @param mem pointer to the pointer to allocated block |
| 142 * @param n the new size in bytes | 148 * @param n the new size in bytes |
| 143 * @return zero on success, non-zero on failure | 149 * @return zero on success, non-zero on failure |
| 144 */ | 150 */ |
| 151 cx_attr_nonnull | |
| 152 cx_attr_nodiscard | |
| 145 int cx_reallocate( | 153 int cx_reallocate( |
| 146 void **mem, | 154 void **mem, |
| 147 size_t n | 155 size_t n |
| 148 ) | 156 ); |
| 149 __attribute__((__nonnull__)); | 157 |
| 158 /** | |
| 159 * Re-allocate a previously allocated block and changes the pointer in-place, | |
| 160 * if necessary. | |
| 161 * | |
| 162 * The size is calculated by multiplying \p nemb and \p size. | |
| 163 * | |
| 164 * \par Error handling | |
| 165 * \c errno will be set by realloc() on failure or when the multiplication of | |
| 166 * \p nmemb and \p size overflows. | |
| 167 * | |
| 168 * @param mem pointer to the pointer to allocated block | |
| 169 * @param nmemb the number of elements | |
| 170 * @param size the size of each element | |
| 171 * @return zero on success, non-zero on failure | |
| 172 */ | |
| 173 cx_attr_nonnull | |
| 174 cx_attr_nodiscard | |
| 175 int cx_reallocatearray( | |
| 176 void **mem, | |
| 177 size_t nmemb, | |
| 178 size_t size | |
| 179 ); | |
| 180 | |
| 181 /** | |
| 182 * Re-allocate a previously allocated block and changes the pointer in-place, | |
| 183 * if necessary. | |
| 184 * | |
| 185 * \par Error handling | |
| 186 * \c errno will be set by realloc() on failure. | |
| 187 * | |
| 188 * @param mem pointer to the pointer to allocated block | |
| 189 * @param n the new size in bytes | |
| 190 * @return zero on success, non-zero on failure | |
| 191 */ | |
| 192 #define cx_reallocate(mem, n) cx_reallocate((void**)(mem), n) | |
| 193 | |
| 194 /** | |
| 195 * Re-allocate a previously allocated block and changes the pointer in-place, | |
| 196 * if necessary. | |
| 197 * | |
| 198 * The size is calculated by multiplying \p nemb and \p size. | |
| 199 * | |
| 200 * \par Error handling | |
| 201 * \c errno will be set by realloc() on failure or when the multiplication of | |
| 202 * \p nmemb and \p size overflows. | |
| 203 * | |
| 204 * @param mem pointer to the pointer to allocated block | |
| 205 * @param nmemb the number of elements | |
| 206 * @param size the size of each element | |
| 207 * @return zero on success, non-zero on failure | |
| 208 */ | |
| 209 #define cx_reallocatearray(mem, nmemb, size) \ | |
| 210 cx_reallocatearray((void**)(mem), nmemb, size) | |
| 211 | |
| 212 /** | |
| 213 * Free a block allocated by this allocator. | |
| 214 * | |
| 215 * \note Freeing a block of a different allocator is undefined. | |
| 216 * | |
| 217 * @param allocator the allocator | |
| 218 * @param mem a pointer to the block to free | |
| 219 */ | |
| 220 cx_attr_nonnull_arg(1) | |
| 221 void cxFree( | |
| 222 const CxAllocator *allocator, | |
| 223 void *mem | |
| 224 ); | |
| 150 | 225 |
| 151 /** | 226 /** |
| 152 * Allocate \p n bytes of memory. | 227 * Allocate \p n bytes of memory. |
| 153 * | 228 * |
| 154 * @param allocator the allocator | 229 * @param allocator the allocator |
| 155 * @param n the number of bytes | 230 * @param n the number of bytes |
| 156 * @return a pointer to the allocated memory | 231 * @return a pointer to the allocated memory |
| 157 */ | 232 */ |
| 233 cx_attr_nodiscard | |
| 234 cx_attr_nonnull | |
| 235 cx_attr_malloc | |
| 236 cx_attr_dealloc_ucx | |
| 237 cx_attr_allocsize(2) | |
| 158 void *cxMalloc( | 238 void *cxMalloc( |
| 159 CxAllocator const *allocator, | 239 const CxAllocator *allocator, |
| 160 size_t n | 240 size_t n |
| 161 ) | 241 ); |
| 162 __attribute__((__malloc__)) | 242 |
| 163 __attribute__((__alloc_size__(2))); | 243 /** |
| 164 | 244 * Re-allocate the previously allocated block in \p mem, making the new block |
| 165 /** | 245 * \p n bytes long. |
| 166 * Re-allocate the previously allocated block in \p mem, making the new block \p n bytes long. | 246 * This function may return the same pointer that was passed to it, if moving |
| 167 * This function may return the same pointer that was passed to it, if moving the memory | 247 * the memory was not necessary. |
| 168 * was not necessary. | |
| 169 * | 248 * |
| 170 * \note Re-allocating a block allocated by a different allocator is undefined. | 249 * \note Re-allocating a block allocated by a different allocator is undefined. |
| 171 * | 250 * |
| 172 * @param allocator the allocator | 251 * @param allocator the allocator |
| 173 * @param mem pointer to the previously allocated block | 252 * @param mem pointer to the previously allocated block |
| 174 * @param n the new size in bytes | 253 * @param n the new size in bytes |
| 175 * @return a pointer to the re-allocated memory | 254 * @return a pointer to the re-allocated memory |
| 176 */ | 255 */ |
| 256 cx_attr_nodiscard | |
| 257 cx_attr_nonnull_arg(1) | |
| 258 cx_attr_dealloc_ucx | |
| 259 cx_attr_allocsize(3) | |
| 177 void *cxRealloc( | 260 void *cxRealloc( |
| 178 CxAllocator const *allocator, | 261 const CxAllocator *allocator, |
| 179 void *mem, | 262 void *mem, |
| 180 size_t n | 263 size_t n |
| 181 ) | 264 ); |
| 182 __attribute__((__warn_unused_result__)) | 265 |
| 183 __attribute__((__alloc_size__(3))); | 266 /** |
| 184 | 267 * Re-allocate the previously allocated block in \p mem, making the new block |
| 185 /** | 268 * \p n bytes long. |
| 186 * Re-allocate a previously allocated block and changes the pointer in-place, if necessary. | 269 * This function may return the same pointer that was passed to it, if moving |
| 270 * the memory was not necessary. | |
| 271 * | |
| 272 * The size is calculated by multiplying \p nemb and \p size. | |
| 273 * If that multiplication overflows, this function returns \c NULL and \c errno | |
| 274 * will be set. | |
| 275 * | |
| 276 * \note Re-allocating a block allocated by a different allocator is undefined. | |
| 277 * | |
| 278 * @param allocator the allocator | |
| 279 * @param mem pointer to the previously allocated block | |
| 280 * @param nmemb the number of elements | |
| 281 * @param size the size of each element | |
| 282 * @return a pointer to the re-allocated memory | |
| 283 */ | |
| 284 cx_attr_nodiscard | |
| 285 cx_attr_nonnull_arg(1) | |
| 286 cx_attr_dealloc_ucx | |
| 287 cx_attr_allocsize(3, 4) | |
| 288 void *cxReallocArray( | |
| 289 const CxAllocator *allocator, | |
| 290 void *mem, | |
| 291 size_t nmemb, | |
| 292 size_t size | |
| 293 ); | |
| 294 | |
| 295 /** | |
| 296 * Re-allocate a previously allocated block and changes the pointer in-place, | |
| 297 * if necessary. | |
| 187 * This function acts like cxRealloc() using the pointer pointed to by \p mem. | 298 * This function acts like cxRealloc() using the pointer pointed to by \p mem. |
| 188 * | 299 * |
| 189 * \note Re-allocating a block allocated by a different allocator is undefined. | 300 * \note Re-allocating a block allocated by a different allocator is undefined. |
| 190 * | 301 * |
| 191 * \par Error handling | 302 * \par Error handling |
| 194 * @param allocator the allocator | 305 * @param allocator the allocator |
| 195 * @param mem pointer to the pointer to allocated block | 306 * @param mem pointer to the pointer to allocated block |
| 196 * @param n the new size in bytes | 307 * @param n the new size in bytes |
| 197 * @return zero on success, non-zero on failure | 308 * @return zero on success, non-zero on failure |
| 198 */ | 309 */ |
| 310 cx_attr_nodiscard | |
| 311 cx_attr_nonnull | |
| 199 int cxReallocate( | 312 int cxReallocate( |
| 200 CxAllocator const *allocator, | 313 const CxAllocator *allocator, |
| 201 void **mem, | 314 void **mem, |
| 202 size_t n | 315 size_t n |
| 203 ) | 316 ); |
| 204 __attribute__((__nonnull__)); | 317 |
| 318 /** | |
| 319 * Re-allocate a previously allocated block and changes the pointer in-place, | |
| 320 * if necessary. | |
| 321 * This function acts like cxRealloc() using the pointer pointed to by \p mem. | |
| 322 * | |
| 323 * \note Re-allocating a block allocated by a different allocator is undefined. | |
| 324 * | |
| 325 * \par Error handling | |
| 326 * \c errno will be set, if the underlying realloc function does so. | |
| 327 * | |
| 328 * @param allocator the allocator | |
| 329 * @param mem pointer to the pointer to allocated block | |
| 330 * @param n the new size in bytes | |
| 331 * @return zero on success, non-zero on failure | |
| 332 */ | |
| 333 #define cxReallocate(allocator, mem, n) \ | |
| 334 cxReallocate(allocator, (void**)(mem), n) | |
| 335 | |
| 336 /** | |
| 337 * Re-allocate a previously allocated block and changes the pointer in-place, | |
| 338 * if necessary. | |
| 339 * This function acts like cxReallocArray() using the pointer pointed to | |
| 340 * by \p mem. | |
| 341 * | |
| 342 * \note Re-allocating a block allocated by a different allocator is undefined. | |
| 343 * | |
| 344 * \par Error handling | |
| 345 * \c errno will be set, if the underlying realloc function does so or the | |
| 346 * multiplication of \p nmemb and \p size overflows. | |
| 347 * | |
| 348 * @param allocator the allocator | |
| 349 * @param mem pointer to the pointer to allocated block | |
| 350 * @param nmemb the number of elements | |
| 351 * @param size the size of each element | |
| 352 * @return zero on success, non-zero on failure | |
| 353 */ | |
| 354 cx_attr_nodiscard | |
| 355 cx_attr_nonnull | |
| 356 int cxReallocateArray( | |
| 357 const CxAllocator *allocator, | |
| 358 void **mem, | |
| 359 size_t nmemb, | |
| 360 size_t size | |
| 361 ); | |
| 362 | |
| 363 /** | |
| 364 * Re-allocate a previously allocated block and changes the pointer in-place, | |
| 365 * if necessary. | |
| 366 * This function acts like cxReallocArray() using the pointer pointed to | |
| 367 * by \p mem. | |
| 368 * | |
| 369 * \note Re-allocating a block allocated by a different allocator is undefined. | |
| 370 * | |
| 371 * \par Error handling | |
| 372 * \c errno will be set, if the underlying realloc function does so or the | |
| 373 * multiplication of \p nmemb and \p size overflows. | |
| 374 * | |
| 375 * @param allocator the allocator | |
| 376 * @param mem pointer to the pointer to allocated block | |
| 377 * @param nmemb the number of elements | |
| 378 * @param size the size of each element | |
| 379 * @return zero on success, non-zero on failure | |
| 380 */ | |
| 381 #define cxReallocateArray(allocator, mem, nmemb, size) \ | |
| 382 cxReallocateArray(allocator, (void**) (mem), nmemb, size) | |
| 205 | 383 |
| 206 /** | 384 /** |
| 207 * Allocate \p nelem elements of \p n bytes each, all initialized to zero. | 385 * Allocate \p nelem elements of \p n bytes each, all initialized to zero. |
| 208 * | 386 * |
| 209 * @param allocator the allocator | 387 * @param allocator the allocator |
| 210 * @param nelem the number of elements | 388 * @param nelem the number of elements |
| 211 * @param n the size of each element in bytes | 389 * @param n the size of each element in bytes |
| 212 * @return a pointer to the allocated memory | 390 * @return a pointer to the allocated memory |
| 213 */ | 391 */ |
| 392 cx_attr_nonnull_arg(1) | |
| 393 cx_attr_nodiscard | |
| 394 cx_attr_malloc | |
| 395 cx_attr_dealloc_ucx | |
| 396 cx_attr_allocsize(2, 3) | |
| 214 void *cxCalloc( | 397 void *cxCalloc( |
| 215 CxAllocator const *allocator, | 398 const CxAllocator *allocator, |
| 216 size_t nelem, | 399 size_t nelem, |
| 217 size_t n | 400 size_t n |
| 218 ) | 401 ); |
| 219 __attribute__((__malloc__)) | |
| 220 __attribute__((__alloc_size__(2, 3))); | |
| 221 | |
| 222 /** | |
| 223 * Free a block allocated by this allocator. | |
| 224 * | |
| 225 * \note Freeing a block of a different allocator is undefined. | |
| 226 * | |
| 227 * @param allocator the allocator | |
| 228 * @param mem a pointer to the block to free | |
| 229 */ | |
| 230 void cxFree( | |
| 231 CxAllocator const *allocator, | |
| 232 void *mem | |
| 233 ) | |
| 234 __attribute__((__nonnull__)); | |
| 235 | 402 |
| 236 #ifdef __cplusplus | 403 #ifdef __cplusplus |
| 237 } // extern "C" | 404 } // extern "C" |
| 238 #endif | 405 #endif |
| 239 | 406 |
