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