comparison: ucx/cx/allocator.h
ucx/cx/allocator.h
- changeset 102
- 64ded9f6a6c6
- parent 101
- 7b3a3130be44
equal
deleted
inserted
replaced
| 101:7b3a3130be44 | 102:64ded9f6a6c6 |
|---|---|
| 63 /** | 63 /** |
| 64 * The allocator's calloc() implementation. | 64 * The allocator's calloc() implementation. |
| 65 */ | 65 */ |
| 66 void *(*calloc)( | 66 void *(*calloc)( |
| 67 void *data, | 67 void *data, |
| 68 size_t nelem, | 68 size_t nmemb, |
| 69 size_t n | 69 size_t size |
| 70 ); | 70 ); |
| 71 | 71 |
| 72 /** | 72 /** |
| 73 * The allocator's free() implementation. | 73 * The allocator's free() implementation. |
| 74 */ | 74 */ |
| 98 typedef struct cx_allocator_s CxAllocator; | 98 typedef struct cx_allocator_s CxAllocator; |
| 99 | 99 |
| 100 /** | 100 /** |
| 101 * A default allocator using standard library malloc() etc. | 101 * A default allocator using standard library malloc() etc. |
| 102 */ | 102 */ |
| 103 extern CxAllocator *cxDefaultAllocator; | 103 cx_attr_export |
| 104 extern const CxAllocator * const cxDefaultAllocator; | |
| 104 | 105 |
| 105 /** | 106 /** |
| 106 * Function pointer type for destructor functions. | 107 * Function pointer type for destructor functions. |
| 107 * | 108 * |
| 108 * A destructor function deallocates possible contents and MAY free the memory | 109 * A destructor function deallocates possible contents and MAY free the memory |
| 129 void *data, | 130 void *data, |
| 130 void *memory | 131 void *memory |
| 131 ); | 132 ); |
| 132 | 133 |
| 133 /** | 134 /** |
| 134 * Re-allocate a previously allocated block and changes the pointer in-place, | 135 * Reallocate a previously allocated block and changes the pointer in-place, |
| 135 * if necessary. | 136 * if necessary. |
| 136 * | 137 * |
| 137 * @par Error handling | 138 * @par Error handling |
| 138 * @c errno will be set by realloc() on failure. | 139 * @c errno will be set by realloc() on failure. |
| 139 * | 140 * |
| 143 * @retval non-zero failure | 144 * @retval non-zero failure |
| 144 * @see cx_reallocatearray() | 145 * @see cx_reallocatearray() |
| 145 */ | 146 */ |
| 146 cx_attr_nonnull | 147 cx_attr_nonnull |
| 147 cx_attr_nodiscard | 148 cx_attr_nodiscard |
| 148 int cx_reallocate( | 149 cx_attr_export |
| 150 int cx_reallocate_( | |
| 149 void **mem, | 151 void **mem, |
| 150 size_t n | 152 size_t n |
| 151 ); | 153 ); |
| 152 | 154 |
| 153 /** | 155 /** |
| 154 * Re-allocate a previously allocated block and changes the pointer in-place, | 156 * Reallocate a previously allocated block and changes the pointer in-place, |
| 155 * if necessary. | 157 * if necessary. |
| 156 * | 158 * |
| 157 * The size is calculated by multiplying @p nemb and @p size. | 159 * The size is calculated by multiplying @p nemb and @p size. |
| 158 * | 160 * |
| 159 * @par Error handling | 161 * @par Error handling |
| 167 * @retval non-zero failure | 169 * @retval non-zero failure |
| 168 * @see cx_reallocate() | 170 * @see cx_reallocate() |
| 169 */ | 171 */ |
| 170 cx_attr_nonnull | 172 cx_attr_nonnull |
| 171 cx_attr_nodiscard | 173 cx_attr_nodiscard |
| 172 int cx_reallocatearray( | 174 cx_attr_export |
| 175 int cx_reallocatearray_( | |
| 173 void **mem, | 176 void **mem, |
| 174 size_t nmemb, | 177 size_t nmemb, |
| 175 size_t size | 178 size_t size |
| 176 ); | 179 ); |
| 177 | 180 |
| 178 /** | 181 /** |
| 179 * Re-allocate a previously allocated block and changes the pointer in-place, | 182 * Reallocate a previously allocated block and changes the pointer in-place, |
| 180 * if necessary. | 183 * if necessary. |
| 181 * | 184 * |
| 182 * @par Error handling | 185 * @par Error handling |
| 183 * @c errno will be set by realloc() on failure. | 186 * @c errno will be set by realloc() on failure. |
| 184 * | 187 * |
| 186 * @param n (@c size_t) the new size in bytes | 189 * @param n (@c size_t) the new size in bytes |
| 187 * @retval zero success | 190 * @retval zero success |
| 188 * @retval non-zero failure | 191 * @retval non-zero failure |
| 189 * @see cx_reallocatearray() | 192 * @see cx_reallocatearray() |
| 190 */ | 193 */ |
| 191 #define cx_reallocate(mem, n) cx_reallocate((void**)(mem), n) | 194 #define cx_reallocate(mem, n) cx_reallocate_((void**)(mem), n) |
| 192 | 195 |
| 193 /** | 196 /** |
| 194 * Re-allocate a previously allocated block and changes the pointer in-place, | 197 * Reallocate a previously allocated block and changes the pointer in-place, |
| 195 * if necessary. | 198 * if necessary. |
| 196 * | 199 * |
| 197 * The size is calculated by multiplying @p nemb and @p size. | 200 * The size is calculated by multiplying @p nemb and @p size. |
| 198 * | 201 * |
| 199 * @par Error handling | 202 * @par Error handling |
| 205 * @param size (@c size_t) the size of each element | 208 * @param size (@c size_t) the size of each element |
| 206 * @retval zero success | 209 * @retval zero success |
| 207 * @retval non-zero failure | 210 * @retval non-zero failure |
| 208 */ | 211 */ |
| 209 #define cx_reallocatearray(mem, nmemb, size) \ | 212 #define cx_reallocatearray(mem, nmemb, size) \ |
| 210 cx_reallocatearray((void**)(mem), nmemb, size) | 213 cx_reallocatearray_((void**)(mem), nmemb, size) |
| 211 | 214 |
| 212 /** | 215 /** |
| 213 * Free a block allocated by this allocator. | 216 * Free a block allocated by this allocator. |
| 214 * | 217 * |
| 215 * @note Freeing a block of a different allocator is undefined. | 218 * @note Freeing a block of a different allocator is undefined. |
| 216 * | 219 * |
| 217 * @param allocator the allocator | 220 * @param allocator the allocator |
| 218 * @param mem a pointer to the block to free | 221 * @param mem a pointer to the block to free |
| 219 */ | 222 */ |
| 220 cx_attr_nonnull_arg(1) | 223 cx_attr_nonnull_arg(1) |
| 224 cx_attr_export | |
| 221 void cxFree( | 225 void cxFree( |
| 222 const CxAllocator *allocator, | 226 const CxAllocator *allocator, |
| 223 void *mem | 227 void *mem |
| 224 ); | 228 ); |
| 225 | 229 |
| 233 cx_attr_nodiscard | 237 cx_attr_nodiscard |
| 234 cx_attr_nonnull | 238 cx_attr_nonnull |
| 235 cx_attr_malloc | 239 cx_attr_malloc |
| 236 cx_attr_dealloc_ucx | 240 cx_attr_dealloc_ucx |
| 237 cx_attr_allocsize(2) | 241 cx_attr_allocsize(2) |
| 242 cx_attr_export | |
| 238 void *cxMalloc( | 243 void *cxMalloc( |
| 239 const CxAllocator *allocator, | 244 const CxAllocator *allocator, |
| 240 size_t n | 245 size_t n |
| 241 ); | 246 ); |
| 242 | 247 |
| 243 /** | 248 /** |
| 244 * Re-allocate the previously allocated block in @p mem, making the new block | 249 * Reallocate the previously allocated block in @p mem, making the new block |
| 245 * @p n bytes long. | 250 * @p n bytes long. |
| 246 * This function may return the same pointer that was passed to it, if moving | 251 * This function may return the same pointer that was passed to it, if moving |
| 247 * the memory was not necessary. | 252 * the memory was not necessary. |
| 248 * | 253 * |
| 249 * @note Re-allocating a block allocated by a different allocator is undefined. | 254 * @note Re-allocating a block allocated by a different allocator is undefined. |
| 250 * | 255 * |
| 251 * @param allocator the allocator | 256 * @param allocator the allocator |
| 252 * @param mem pointer to the previously allocated block | 257 * @param mem pointer to the previously allocated block |
| 253 * @param n the new size in bytes | 258 * @param n the new size in bytes |
| 254 * @return a pointer to the re-allocated memory | 259 * @return a pointer to the reallocated memory |
| 255 */ | 260 */ |
| 256 cx_attr_nodiscard | 261 cx_attr_nodiscard |
| 257 cx_attr_nonnull_arg(1) | 262 cx_attr_nonnull_arg(1) |
| 258 cx_attr_dealloc_ucx | 263 cx_attr_dealloc_ucx |
| 259 cx_attr_allocsize(3) | 264 cx_attr_allocsize(3) |
| 265 cx_attr_export | |
| 260 void *cxRealloc( | 266 void *cxRealloc( |
| 261 const CxAllocator *allocator, | 267 const CxAllocator *allocator, |
| 262 void *mem, | 268 void *mem, |
| 263 size_t n | 269 size_t n |
| 264 ); | 270 ); |
| 265 | 271 |
| 266 /** | 272 /** |
| 267 * Re-allocate the previously allocated block in @p mem, making the new block | 273 * Reallocate the previously allocated block in @p mem, making the new block |
| 268 * @p n bytes long. | 274 * @p n bytes long. |
| 269 * This function may return the same pointer that was passed to it, if moving | 275 * This function may return the same pointer that was passed to it, if moving |
| 270 * the memory was not necessary. | 276 * the memory was not necessary. |
| 271 * | 277 * |
| 272 * The size is calculated by multiplying @p nemb and @p size. | 278 * The size is calculated by multiplying @p nemb and @p size. |
| 277 * | 283 * |
| 278 * @param allocator the allocator | 284 * @param allocator the allocator |
| 279 * @param mem pointer to the previously allocated block | 285 * @param mem pointer to the previously allocated block |
| 280 * @param nmemb the number of elements | 286 * @param nmemb the number of elements |
| 281 * @param size the size of each element | 287 * @param size the size of each element |
| 282 * @return a pointer to the re-allocated memory | 288 * @return a pointer to the reallocated memory |
| 283 */ | 289 */ |
| 284 cx_attr_nodiscard | 290 cx_attr_nodiscard |
| 285 cx_attr_nonnull_arg(1) | 291 cx_attr_nonnull_arg(1) |
| 286 cx_attr_dealloc_ucx | 292 cx_attr_dealloc_ucx |
| 287 cx_attr_allocsize(3, 4) | 293 cx_attr_allocsize(3, 4) |
| 294 cx_attr_export | |
| 288 void *cxReallocArray( | 295 void *cxReallocArray( |
| 289 const CxAllocator *allocator, | 296 const CxAllocator *allocator, |
| 290 void *mem, | 297 void *mem, |
| 291 size_t nmemb, | 298 size_t nmemb, |
| 292 size_t size | 299 size_t size |
| 293 ); | 300 ); |
| 294 | 301 |
| 295 /** | 302 /** |
| 296 * Re-allocate a previously allocated block and changes the pointer in-place, | 303 * Reallocate a previously allocated block and changes the pointer in-place, |
| 297 * if necessary. | 304 * if necessary. |
| 298 * This function acts like cxRealloc() using the pointer pointed to by @p mem. | 305 * This function acts like cxRealloc() using the pointer pointed to by @p mem. |
| 299 * | 306 * |
| 300 * @note Re-allocating a block allocated by a different allocator is undefined. | 307 * @note Re-allocating a block allocated by a different allocator is undefined. |
| 301 * | 308 * |
| 308 * @retval zero success | 315 * @retval zero success |
| 309 * @retval non-zero failure | 316 * @retval non-zero failure |
| 310 */ | 317 */ |
| 311 cx_attr_nodiscard | 318 cx_attr_nodiscard |
| 312 cx_attr_nonnull | 319 cx_attr_nonnull |
| 313 int cxReallocate( | 320 cx_attr_export |
| 321 int cxReallocate_( | |
| 314 const CxAllocator *allocator, | 322 const CxAllocator *allocator, |
| 315 void **mem, | 323 void **mem, |
| 316 size_t n | 324 size_t n |
| 317 ); | 325 ); |
| 318 | 326 |
| 319 /** | 327 /** |
| 320 * Re-allocate a previously allocated block and changes the pointer in-place, | 328 * Reallocate a previously allocated block and changes the pointer in-place, |
| 321 * if necessary. | 329 * if necessary. |
| 322 * This function acts like cxRealloc() using the pointer pointed to by @p mem. | 330 * This function acts like cxRealloc() using the pointer pointed to by @p mem. |
| 323 * | 331 * |
| 324 * @note Re-allocating a block allocated by a different allocator is undefined. | 332 * @note Re-allocating a block allocated by a different allocator is undefined. |
| 325 * | 333 * |
| 331 * @param n (@c size_t) the new size in bytes | 339 * @param n (@c size_t) the new size in bytes |
| 332 * @retval zero success | 340 * @retval zero success |
| 333 * @retval non-zero failure | 341 * @retval non-zero failure |
| 334 */ | 342 */ |
| 335 #define cxReallocate(allocator, mem, n) \ | 343 #define cxReallocate(allocator, mem, n) \ |
| 336 cxReallocate(allocator, (void**)(mem), n) | 344 cxReallocate_(allocator, (void**)(mem), n) |
| 337 | 345 |
| 338 /** | 346 /** |
| 339 * Re-allocate a previously allocated block and changes the pointer in-place, | 347 * Reallocate a previously allocated block and changes the pointer in-place, |
| 340 * if necessary. | 348 * if necessary. |
| 341 * This function acts like cxReallocArray() using the pointer pointed to | 349 * This function acts like cxReallocArray() using the pointer pointed to |
| 342 * by @p mem. | 350 * by @p mem. |
| 343 * | 351 * |
| 344 * @note Re-allocating a block allocated by a different allocator is undefined. | 352 * @note Re-allocating a block allocated by a different allocator is undefined. |
| 354 * @retval zero success | 362 * @retval zero success |
| 355 * @retval non-zero on failure | 363 * @retval non-zero on failure |
| 356 */ | 364 */ |
| 357 cx_attr_nodiscard | 365 cx_attr_nodiscard |
| 358 cx_attr_nonnull | 366 cx_attr_nonnull |
| 359 int cxReallocateArray( | 367 cx_attr_export |
| 368 int cxReallocateArray_( | |
| 360 const CxAllocator *allocator, | 369 const CxAllocator *allocator, |
| 361 void **mem, | 370 void **mem, |
| 362 size_t nmemb, | 371 size_t nmemb, |
| 363 size_t size | 372 size_t size |
| 364 ); | 373 ); |
| 365 | 374 |
| 366 /** | 375 /** |
| 367 * Re-allocate a previously allocated block and changes the pointer in-place, | 376 * Reallocate a previously allocated block and changes the pointer in-place, |
| 368 * if necessary. | 377 * if necessary. |
| 369 * This function acts like cxReallocArray() using the pointer pointed to | 378 * This function acts like cxReallocArray() using the pointer pointed to |
| 370 * by @p mem. | 379 * by @p mem. |
| 371 * | 380 * |
| 372 * @note Re-allocating a block allocated by a different allocator is undefined. | 381 * @note Re-allocating a block allocated by a different allocator is undefined. |
| 381 * @param size (@c size_t) the size of each element | 390 * @param size (@c size_t) the size of each element |
| 382 * @retval zero success | 391 * @retval zero success |
| 383 * @retval non-zero failure | 392 * @retval non-zero failure |
| 384 */ | 393 */ |
| 385 #define cxReallocateArray(allocator, mem, nmemb, size) \ | 394 #define cxReallocateArray(allocator, mem, nmemb, size) \ |
| 386 cxReallocateArray(allocator, (void**) (mem), nmemb, size) | 395 cxReallocateArray_(allocator, (void**) (mem), nmemb, size) |
| 387 | 396 |
| 388 /** | 397 /** |
| 389 * Allocate @p nelem elements of @p n bytes each, all initialized to zero. | 398 * Allocate @p nmemb elements of @p n bytes each, all initialized to zero. |
| 390 * | 399 * |
| 391 * @param allocator the allocator | 400 * @param allocator the allocator |
| 392 * @param nelem the number of elements | 401 * @param nmemb the number of elements |
| 393 * @param n the size of each element in bytes | 402 * @param size the size of each element in bytes |
| 394 * @return a pointer to the allocated memory | 403 * @return a pointer to the allocated memory |
| 395 */ | 404 */ |
| 396 cx_attr_nonnull_arg(1) | 405 cx_attr_nonnull_arg(1) |
| 397 cx_attr_nodiscard | 406 cx_attr_nodiscard |
| 398 cx_attr_malloc | 407 cx_attr_malloc |
| 399 cx_attr_dealloc_ucx | 408 cx_attr_dealloc_ucx |
| 400 cx_attr_allocsize(2, 3) | 409 cx_attr_allocsize(2, 3) |
| 410 cx_attr_export | |
| 401 void *cxCalloc( | 411 void *cxCalloc( |
| 402 const CxAllocator *allocator, | 412 const CxAllocator *allocator, |
| 403 size_t nelem, | 413 size_t nmemb, |
| 404 size_t n | 414 size_t size |
| 405 ); | 415 ); |
| 406 | 416 |
| 407 #ifdef __cplusplus | 417 #ifdef __cplusplus |
| 408 } // extern "C" | 418 } // extern "C" |
| 409 #endif | 419 #endif |
