Mercurial > hg > dav / file comparison

comparison: ucx/cx/allocator.h

ucx/cx/allocator.h

branch
dav-2
changeset 889
42cdbf9bbd49
parent 886
da79af4baec8
equal deleted inserted replaced
887:26541c37b619 889:42cdbf9bbd49
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 void *(*malloc)( 49 void *(*malloc)(void *data, size_t n);
50 void *data,
51 size_t n
52 );
53 50
54 /** 51 /**
55 * The allocator's realloc() implementation. 52 * The allocator's realloc() implementation.
56 */ 53 */
57 void *(*realloc)( 54 void *(*realloc)(void *data, void *mem, size_t n);
58 void *data,
59 void *mem,
60 size_t n
61 );
62 55
63 /** 56 /**
64 * The allocator's calloc() implementation. 57 * The allocator's calloc() implementation.
65 */ 58 */
66 void *(*calloc)( 59 void *(*calloc)(void *data, size_t nmemb, size_t size);
67 void *data,
68 size_t nmemb,
69 size_t size
70 );
71 60
72 /** 61 /**
73 * The allocator's free() implementation. 62 * The allocator's free() implementation.
74 */ 63 */
75 void (*free)( 64 void (*free)(void *data, void *mem);
76 void *data,
77 void *mem
78 );
79 } cx_allocator_class; 65 } cx_allocator_class;
80 66
81 /** 67 /**
82 * Structure holding the data for an allocator. 68 * Structure holding the data for an allocator.
83 */ 69 */
98 typedef struct cx_allocator_s CxAllocator; 84 typedef struct cx_allocator_s CxAllocator;
99 85
100 /** 86 /**
101 * A pre-defined allocator using standard library malloc() etc. 87 * A pre-defined allocator using standard library malloc() etc.
102 */ 88 */
103 cx_attr_export 89 CX_EXPORT extern const CxAllocator * const cxStdlibAllocator;
104 extern const CxAllocator * const cxStdlibAllocator;
105 90
106 /** 91 /**
107 * The default allocator that is used by UCX. 92 * The default allocator that is used by UCX.
108 * Initialized with cxStdlibAllocator, but you may change it. 93 * Initialized with cxStdlibAllocator, but you may change it.
109 */ 94 */
110 cx_attr_export 95 CX_EXPORT extern const CxAllocator * cxDefaultAllocator;
111 extern const CxAllocator * cxDefaultAllocator;
112 96
113 /** 97 /**
114 * Function pointer type for destructor functions. 98 * Function pointer type for destructor functions.
115 * 99 *
116 * A destructor function deallocates possible contents and MAY free the memory 100 * A destructor function deallocates possible contents and MAY free the memory
131 * that particular implementation. 115 * that particular implementation.
132 * 116 *
133 * @param data an optional pointer to custom data 117 * @param data an optional pointer to custom data
134 * @param memory a pointer to the object to destruct 118 * @param memory a pointer to the object to destruct
135 */ 119 */
136 typedef void (*cx_destructor_func2)( 120 typedef void (*cx_destructor_func2)(void *data, void *memory);
137 void *data, 121
138 void *memory 122
139 ); 123 /**
124 * Function pointer type for clone functions.
125 *
126 * A clone function is supposed to create a deep copy of the memory pointed to
127 * by the @p source pointer.
128 * If the @p target pointer is non-null, the clone function is supposed to store
129 * the copy into that memory region.
130 * Otherwise, the clone function shall use the specified @p allocator to create
131 * a new object.
132 *
133 * The return value of a clone function is always a pointer to the target
134 * memory region, or @c NULL if any allocation failed.
135 * A clone function SHOULD NOT fail for any other reason than an allocation
136 * failure.
137 *
138 * @param target the target memory or @c NULL, if memory shall be allocated
139 * @param source the source memory
140 * @param allocator the allocator that shall be used
141 * @param data optional additional data
142 * @return either the specified @p target, a pointer to the allocated memory,
143 * or @c NULL, if any error occurred
144 */
145 typedef void*(cx_clone_func)(void *target, const void *source,
146 const CxAllocator *allocator, void *data);
140 147
141 /** 148 /**
142 * Reallocate a previously allocated block and changes the pointer in-place, 149 * Reallocate a previously allocated block and changes the pointer in-place,
143 * if necessary. 150 * if necessary.
144 * 151 *
151 * @param n the new size in bytes 158 * @param n the new size in bytes
152 * @retval zero success 159 * @retval zero success
153 * @retval non-zero failure 160 * @retval non-zero failure
154 * @see cx_reallocatearray() 161 * @see cx_reallocatearray()
155 */ 162 */
156 cx_attr_nonnull 163 cx_attr_nonnull cx_attr_nodiscard
157 cx_attr_nodiscard 164 CX_EXPORT int cx_reallocate_(void **mem, size_t n);
158 cx_attr_export
159 int cx_reallocate_(
160 void **mem,
161 size_t n
162 );
163 165
164 /** 166 /**
165 * Reallocate a previously allocated block and changes the pointer in-place, 167 * Reallocate a previously allocated block and changes the pointer in-place,
166 * if necessary. 168 * if necessary.
167 * 169 *
178 * @param size the size of each element 180 * @param size the size of each element
179 * @retval zero success 181 * @retval zero success
180 * @retval non-zero failure 182 * @retval non-zero failure
181 * @see cx_reallocate() 183 * @see cx_reallocate()
182 */ 184 */
183 cx_attr_nonnull 185 cx_attr_nonnull cx_attr_nodiscard
184 cx_attr_nodiscard 186 CX_EXPORT int cx_reallocatearray_(void **mem, size_t nmemb, size_t size);
185 cx_attr_export
186 int cx_reallocatearray_(
187 void **mem,
188 size_t nmemb,
189 size_t size
190 );
191 187
192 /** 188 /**
193 * Reallocate a previously allocated block and changes the pointer in-place, 189 * Reallocate a previously allocated block and changes the pointer in-place,
194 * if necessary. 190 * if necessary.
195 * 191 *
242 * 238 *
243 * @param allocator the allocator 239 * @param allocator the allocator
244 * @param mem a pointer to the block to free 240 * @param mem a pointer to the block to free
245 */ 241 */
246 cx_attr_nonnull_arg(1) 242 cx_attr_nonnull_arg(1)
247 cx_attr_export 243 CX_EXPORT void cxFree(const CxAllocator *allocator, void *mem);
248 void cxFree(
249 const CxAllocator *allocator,
250 void *mem
251 );
252 244
253 /** 245 /**
254 * Allocate @p n bytes of memory. 246 * Allocate @p n bytes of memory.
255 * 247 *
256 * @param allocator the allocator 248 * @param allocator the allocator
257 * @param n the number of bytes 249 * @param n the number of bytes
258 * @return a pointer to the allocated memory 250 * @return a pointer to the allocated memory
259 */ 251 */
260 cx_attr_nodiscard 252 cx_attr_nodiscard cx_attr_nonnull
261 cx_attr_nonnull 253 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
262 cx_attr_malloc 254 CX_EXPORT void *cxMalloc(const CxAllocator *allocator, size_t n);
263 cx_attr_dealloc_ucx
264 cx_attr_allocsize(2)
265 cx_attr_export
266 void *cxMalloc(
267 const CxAllocator *allocator,
268 size_t n
269 );
270 255
271 /** 256 /**
272 * Reallocate the previously allocated block in @p mem, making the new block 257 * Reallocate the previously allocated block in @p mem, making the new block
273 * @p n bytes long. 258 * @p n bytes long.
274 * This function may return the same pointer that was passed to it, if moving 259 * This function may return the same pointer passed to it if moving
275 * the memory was not necessary. 260 * the memory was not necessary.
276 * 261 *
277 * @note Re-allocating a block allocated by a different allocator is undefined. 262 * @note Re-allocating a block allocated by a different allocator is undefined.
278 * 263 *
279 * @param allocator the allocator 264 * @param allocator the allocator
280 * @param mem pointer to the previously allocated block 265 * @param mem pointer to the previously allocated block
281 * @param n the new size in bytes 266 * @param n the new size in bytes
282 * @return a pointer to the reallocated memory 267 * @return a pointer to the reallocated memory
283 */ 268 */
284 cx_attr_nodiscard 269 cx_attr_nodiscard cx_attr_nonnull_arg(1)
285 cx_attr_nonnull_arg(1) 270 cx_attr_dealloc_ucx cx_attr_allocsize(3)
286 cx_attr_dealloc_ucx 271 CX_EXPORT void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n);
287 cx_attr_allocsize(3)
288 cx_attr_export
289 void *cxRealloc(
290 const CxAllocator *allocator,
291 void *mem,
292 size_t n
293 );
294 272
295 /** 273 /**
296 * Reallocate the previously allocated block in @p mem, making the new block 274 * Reallocate the previously allocated block in @p mem, making the new block
297 * @p n bytes long. 275 * @p n bytes long.
298 * This function may return the same pointer that was passed to it, if moving 276 * This function may return the same pointer passed to it if moving
299 * the memory was not necessary. 277 * the memory was not necessary.
300 * 278 *
301 * The size is calculated by multiplying @p nemb and @p size. 279 * The size is calculated by multiplying @p nemb and @p size.
302 * If that multiplication overflows, this function returns @c NULL and @c errno 280 * If that multiplication overflows, this function returns @c NULL, and @c errno
303 * will be set. 281 * will be set.
304 * 282 *
305 * @note Re-allocating a block allocated by a different allocator is undefined. 283 * @note Re-allocating a block allocated by a different allocator is undefined.
306 * 284 *
307 * @param allocator the allocator 285 * @param allocator the allocator
308 * @param mem pointer to the previously allocated block 286 * @param mem pointer to the previously allocated block
309 * @param nmemb the number of elements 287 * @param nmemb the number of elements
310 * @param size the size of each element 288 * @param size the size of each element
311 * @return a pointer to the reallocated memory 289 * @return a pointer to the reallocated memory
312 */ 290 */
313 cx_attr_nodiscard 291 cx_attr_nodiscard cx_attr_nonnull_arg(1)
314 cx_attr_nonnull_arg(1) 292 cx_attr_dealloc_ucx cx_attr_allocsize(3, 4)
315 cx_attr_dealloc_ucx 293 CX_EXPORT void *cxReallocArray(const CxAllocator *allocator,
316 cx_attr_allocsize(3, 4) 294 void *mem, size_t nmemb, size_t size);
317 cx_attr_export
318 void *cxReallocArray(
319 const CxAllocator *allocator,
320 void *mem,
321 size_t nmemb,
322 size_t size
323 );
324 295
325 /** 296 /**
326 * Reallocate a previously allocated block and changes the pointer in-place, 297 * Reallocate a previously allocated block and changes the pointer in-place,
327 * if necessary. 298 * if necessary.
328 * This function acts like cxRealloc() using the pointer pointed to by @p mem. 299 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
329 * 300 *
330 * @note Re-allocating a block allocated by a different allocator is undefined. 301 * @note Re-allocating a block allocated by a different allocator is undefined.
331 * 302 *
332 * @par Error handling 303 * @par Error handling
333 * @c errno will be set, if the underlying realloc function does so. 304 * @c errno will be set if the underlying realloc function does so.
334 * 305 *
335 * @param allocator the allocator 306 * @param allocator the allocator
336 * @param mem pointer to the pointer to allocated block 307 * @param mem pointer to the pointer to allocated block
337 * @param n the new size in bytes 308 * @param n the new size in bytes
338 * @retval zero success 309 * @retval zero success
339 * @retval non-zero failure 310 * @retval non-zero failure
340 */ 311 */
341 cx_attr_nodiscard 312 cx_attr_nodiscard cx_attr_nonnull
342 cx_attr_nonnull 313 CX_EXPORT int cxReallocate_(const CxAllocator *allocator, void **mem, size_t n);
343 cx_attr_export
344 int cxReallocate_(
345 const CxAllocator *allocator,
346 void **mem,
347 size_t n
348 );
349 314
350 /** 315 /**
351 * Reallocate a previously allocated block and changes the pointer in-place, 316 * Reallocate a previously allocated block and changes the pointer in-place,
352 * if necessary. 317 * if necessary.
353 * This function acts like cxRealloc() using the pointer pointed to by @p mem. 318 * This function acts like cxRealloc() using the pointer pointed to by @p mem.
354 * 319 *
355 * @note Re-allocating a block allocated by a different allocator is undefined. 320 * @note Re-allocating a block allocated by a different allocator is undefined.
356 * 321 *
357 * @par Error handling 322 * @par Error handling
358 * @c errno will be set, if the underlying realloc function does so. 323 * @c errno will be set if the underlying realloc function does so.
359 * 324 *
360 * @param allocator (@c CxAllocator*) the allocator 325 * @param allocator (@c CxAllocator*) the allocator
361 * @param mem (@c void**) pointer to the pointer to allocated block 326 * @param mem (@c void**) pointer to the pointer to allocated block
362 * @param n (@c size_t) the new size in bytes 327 * @param n (@c size_t) the new size in bytes
363 * @retval zero success 328 * @retval zero success
383 * @param nmemb the number of elements 348 * @param nmemb the number of elements
384 * @param size the size of each element 349 * @param size the size of each element
385 * @retval zero success 350 * @retval zero success
386 * @retval non-zero on failure 351 * @retval non-zero on failure
387 */ 352 */
388 cx_attr_nodiscard 353 cx_attr_nodiscard cx_attr_nonnull
389 cx_attr_nonnull 354 CX_EXPORT int cxReallocateArray_(const CxAllocator *allocator,
390 cx_attr_export 355 void **mem, size_t nmemb, size_t size);
391 int cxReallocateArray_(
392 const CxAllocator *allocator,
393 void **mem,
394 size_t nmemb,
395 size_t size
396 );
397 356
398 /** 357 /**
399 * Reallocate a previously allocated block and changes the pointer in-place, 358 * Reallocate a previously allocated block and changes the pointer in-place,
400 * if necessary. 359 * if necessary.
401 * This function acts like cxReallocArray() using the pointer pointed to 360 * This function acts like cxReallocArray() using the pointer pointed to
423 * @param allocator the allocator 382 * @param allocator the allocator
424 * @param nmemb the number of elements 383 * @param nmemb the number of elements
425 * @param size the size of each element in bytes 384 * @param size the size of each element in bytes
426 * @return a pointer to the allocated memory 385 * @return a pointer to the allocated memory
427 */ 386 */
428 cx_attr_nonnull_arg(1) 387 cx_attr_nonnull_arg(1) cx_attr_nodiscard
429 cx_attr_nodiscard 388 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2, 3)
430 cx_attr_malloc 389 CX_EXPORT void *cxCalloc(const CxAllocator *allocator, size_t nmemb, size_t size);
431 cx_attr_dealloc_ucx
432 cx_attr_allocsize(2, 3)
433 cx_attr_export
434 void *cxCalloc(
435 const CxAllocator *allocator,
436 size_t nmemb,
437 size_t size
438 );
439 390
440 /** 391 /**
441 * Allocate @p n bytes of memory and sets every byte to zero. 392 * Allocate @p n bytes of memory and sets every byte to zero.
442 * 393 *
443 * @param allocator the allocator 394 * @param allocator the allocator
444 * @param n the number of bytes 395 * @param n the number of bytes
445 * @return a pointer to the allocated memory 396 * @return a pointer to the allocated memory
446 */ 397 */
447 cx_attr_nodiscard 398 cx_attr_nodiscard cx_attr_nonnull
448 cx_attr_nonnull 399 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
449 cx_attr_malloc 400 CX_EXPORT void *cxZalloc(const CxAllocator *allocator, size_t n);
450 cx_attr_dealloc_ucx
451 cx_attr_allocsize(2)
452 cx_attr_export
453 void *cxZalloc(
454 const CxAllocator *allocator,
455 size_t n
456 );
457 401
458 /** 402 /**
459 * Convenience macro that invokes cxMalloc() with the cxDefaultAllocator. 403 * Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
460 */ 404 */
461 #define cxMallocDefault(...) cxMalloc(cxDefaultAllocator, __VA_ARGS__) 405 #define cxMallocDefault(...) cxMalloc(cxDefaultAllocator, __VA_ARGS__)

Mercurial Repository: dav

mercurial