Mercurial > hg > dav / file comparison

comparison: ucx/cx/allocator.h

ucx/cx/allocator.h

changeset 888
af685cc9d623
parent 854
1c8401ece69e
equal deleted inserted replaced
877:b60487c3ec36 888:af685cc9d623
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 */
96 * High-Level type alias for the allocator type. 82 * High-Level type alias for the allocator type.
97 */ 83 */
98 typedef struct cx_allocator_s CxAllocator; 84 typedef struct cx_allocator_s CxAllocator;
99 85
100 /** 86 /**
101 * A default 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 cxDefaultAllocator; 90
91 /**
92 * The default allocator that is used by UCX.
93 * Initialized with cxStdlibAllocator, but you may change it.
94 */
95 CX_EXPORT extern const CxAllocator * cxDefaultAllocator;
105 96
106 /** 97 /**
107 * Function pointer type for destructor functions. 98 * Function pointer type for destructor functions.
108 * 99 *
109 * A destructor function deallocates possible contents and MAY free the memory 100 * A destructor function deallocates possible contents and MAY free the memory
124 * that particular implementation. 115 * that particular implementation.
125 * 116 *
126 * @param data an optional pointer to custom data 117 * @param data an optional pointer to custom data
127 * @param memory a pointer to the object to destruct 118 * @param memory a pointer to the object to destruct
128 */ 119 */
129 typedef void (*cx_destructor_func2)( 120 typedef void (*cx_destructor_func2)(void *data, void *memory);
130 void *data, 121
131 void *memory 122
132 ); 123 /**
133 124 * Function pointer type for clone functions.
134 /** 125 *
135 * Reallocate a previously allocated block and changes the pointer in-place, 126 * A clone function is supposed to create a deep copy of the memory pointed to
136 * if necessary. 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);
147
148 /**
149 * Reallocate a previously allocated block and changes the pointer in-place,
150 * if necessary.
151 *
152 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
137 * 153 *
138 * @par Error handling 154 * @par Error handling
139 * @c errno will be set by realloc() on failure. 155 * @c errno will be set by realloc() on failure.
140 * 156 *
141 * @param mem pointer to the pointer to allocated block 157 * @param mem pointer to the pointer to allocated block
142 * @param n the new size in bytes 158 * @param n the new size in bytes
143 * @retval zero success 159 * @retval zero success
144 * @retval non-zero failure 160 * @retval non-zero failure
145 * @see cx_reallocatearray() 161 * @see cx_reallocatearray()
146 */ 162 */
147 cx_attr_nonnull 163 cx_attr_nonnull cx_attr_nodiscard
148 cx_attr_nodiscard 164 CX_EXPORT int cx_reallocate_(void **mem, size_t n);
149 cx_attr_export
150 int cx_reallocate_(
151 void **mem,
152 size_t n
153 );
154 165
155 /** 166 /**
156 * Reallocate a previously allocated block and changes the pointer in-place, 167 * Reallocate a previously allocated block and changes the pointer in-place,
157 * if necessary. 168 * if necessary.
158 * 169 *
159 * The size is calculated by multiplying @p nemb and @p size. 170 * The size is calculated by multiplying @p nemb and @p size.
171 *
172 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
160 * 173 *
161 * @par Error handling 174 * @par Error handling
162 * @c errno will be set by realloc() on failure or when the multiplication of 175 * @c errno will be set by realloc() on failure or when the multiplication of
163 * @p nmemb and @p size overflows. 176 * @p nmemb and @p size overflows.
164 * 177 *
167 * @param size the size of each element 180 * @param size the size of each element
168 * @retval zero success 181 * @retval zero success
169 * @retval non-zero failure 182 * @retval non-zero failure
170 * @see cx_reallocate() 183 * @see cx_reallocate()
171 */ 184 */
172 cx_attr_nonnull 185 cx_attr_nonnull cx_attr_nodiscard
173 cx_attr_nodiscard 186 CX_EXPORT int cx_reallocatearray_(void **mem, size_t nmemb, size_t size);
174 cx_attr_export 187
175 int cx_reallocatearray_( 188 /**
176 void **mem, 189 * Reallocate a previously allocated block and changes the pointer in-place,
177 size_t nmemb, 190 * if necessary.
178 size_t size 191 *
179 ); 192 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
180
181 /**
182 * Reallocate a previously allocated block and changes the pointer in-place,
183 * if necessary.
184 * 193 *
185 * @par Error handling 194 * @par Error handling
186 * @c errno will be set by realloc() on failure. 195 * @c errno will be set by realloc() on failure.
187 * 196 *
188 * @param mem (@c void**) pointer to the pointer to allocated block 197 * @param mem (@c void**) pointer to the pointer to allocated block
196 /** 205 /**
197 * Reallocate a previously allocated block and changes the pointer in-place, 206 * Reallocate a previously allocated block and changes the pointer in-place,
198 * if necessary. 207 * if necessary.
199 * 208 *
200 * The size is calculated by multiplying @p nemb and @p size. 209 * The size is calculated by multiplying @p nemb and @p size.
210 *
211 * @note This will use stdlib reallocate and @em not the cxDefaultAllocator.
201 * 212 *
202 * @par Error handling 213 * @par Error handling
203 * @c errno will be set by realloc() on failure or when the multiplication of 214 * @c errno will be set by realloc() on failure or when the multiplication of
204 * @p nmemb and @p size overflows. 215 * @p nmemb and @p size overflows.
205 * 216 *
211 */ 222 */
212 #define cx_reallocatearray(mem, nmemb, size) \ 223 #define cx_reallocatearray(mem, nmemb, size) \
213 cx_reallocatearray_((void**)(mem), nmemb, size) 224 cx_reallocatearray_((void**)(mem), nmemb, size)
214 225
215 /** 226 /**
227 * Allocates memory and sets every byte to zero.
228 *
229 * @param n (@c size_t) the number of bytes
230 * @return (@c void*) a pointer to the allocated memory
231 */
232 #define cx_zalloc(n) calloc(1, n)
233
234 /**
216 * Free a block allocated by this allocator. 235 * Free a block allocated by this allocator.
217 * 236 *
218 * @note Freeing a block of a different allocator is undefined. 237 * @note Freeing a block of a different allocator is undefined.
219 * 238 *
220 * @param allocator the allocator 239 * @param allocator the allocator
221 * @param mem a pointer to the block to free 240 * @param mem a pointer to the block to free
222 */ 241 */
223 cx_attr_nonnull_arg(1) 242 cx_attr_nonnull_arg(1)
224 cx_attr_export 243 CX_EXPORT void cxFree(const CxAllocator *allocator, void *mem);
225 void cxFree(
226 const CxAllocator *allocator,
227 void *mem
228 );
229 244
230 /** 245 /**
231 * Allocate @p n bytes of memory. 246 * Allocate @p n bytes of memory.
232 * 247 *
233 * @param allocator the allocator 248 * @param allocator the allocator
234 * @param n the number of bytes 249 * @param n the number of bytes
235 * @return a pointer to the allocated memory 250 * @return a pointer to the allocated memory
236 */ 251 */
237 cx_attr_nodiscard 252 cx_attr_nodiscard cx_attr_nonnull
238 cx_attr_nonnull 253 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
239 cx_attr_malloc 254 CX_EXPORT void *cxMalloc(const CxAllocator *allocator, size_t n);
240 cx_attr_dealloc_ucx
241 cx_attr_allocsize(2)
242 cx_attr_export
243 void *cxMalloc(
244 const CxAllocator *allocator,
245 size_t n
246 );
247 255
248 /** 256 /**
249 * 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
250 * @p n bytes long. 258 * @p n bytes long.
251 * 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
252 * the memory was not necessary. 260 * the memory was not necessary.
253 * 261 *
254 * @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.
255 * 263 *
256 * @param allocator the allocator 264 * @param allocator the allocator
257 * @param mem pointer to the previously allocated block 265 * @param mem pointer to the previously allocated block
258 * @param n the new size in bytes 266 * @param n the new size in bytes
259 * @return a pointer to the reallocated memory 267 * @return a pointer to the reallocated memory
260 */ 268 */
261 cx_attr_nodiscard 269 cx_attr_nodiscard cx_attr_nonnull_arg(1)
262 cx_attr_nonnull_arg(1) 270 cx_attr_dealloc_ucx cx_attr_allocsize(3)
263 cx_attr_dealloc_ucx 271 CX_EXPORT void *cxRealloc(const CxAllocator *allocator, void *mem, size_t n);
264 cx_attr_allocsize(3)
265 cx_attr_export
266 void *cxRealloc(
267 const CxAllocator *allocator,
268 void *mem,
269 size_t n
270 );
271 272
272 /** 273 /**
273 * 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
274 * @p n bytes long. 275 * @p n bytes long.
275 * 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
276 * the memory was not necessary. 277 * the memory was not necessary.
277 * 278 *
278 * The size is calculated by multiplying @p nemb and @p size. 279 * The size is calculated by multiplying @p nemb and @p size.
279 * 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
280 * will be set. 281 * will be set.
281 * 282 *
282 * @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.
283 * 284 *
284 * @param allocator the allocator 285 * @param allocator the allocator
285 * @param mem pointer to the previously allocated block 286 * @param mem pointer to the previously allocated block
286 * @param nmemb the number of elements 287 * @param nmemb the number of elements
287 * @param size the size of each element 288 * @param size the size of each element
288 * @return a pointer to the reallocated memory 289 * @return a pointer to the reallocated memory
289 */ 290 */
290 cx_attr_nodiscard 291 cx_attr_nodiscard cx_attr_nonnull_arg(1)
291 cx_attr_nonnull_arg(1) 292 cx_attr_dealloc_ucx cx_attr_allocsize(3, 4)
292 cx_attr_dealloc_ucx 293 CX_EXPORT void *cxReallocArray(const CxAllocator *allocator,
293 cx_attr_allocsize(3, 4) 294 void *mem, size_t nmemb, size_t size);
294 cx_attr_export
295 void *cxReallocArray(
296 const CxAllocator *allocator,
297 void *mem,
298 size_t nmemb,
299 size_t size
300 );
301 295
302 /** 296 /**
303 * Reallocate a previously allocated block and changes the pointer in-place, 297 * Reallocate a previously allocated block and changes the pointer in-place,
304 * if necessary. 298 * if necessary.
305 * 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.
306 * 300 *
307 * @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.
308 * 302 *
309 * @par Error handling 303 * @par Error handling
310 * @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.
311 * 305 *
312 * @param allocator the allocator 306 * @param allocator the allocator
313 * @param mem pointer to the pointer to allocated block 307 * @param mem pointer to the pointer to allocated block
314 * @param n the new size in bytes 308 * @param n the new size in bytes
315 * @retval zero success 309 * @retval zero success
316 * @retval non-zero failure 310 * @retval non-zero failure
317 */ 311 */
318 cx_attr_nodiscard 312 cx_attr_nodiscard cx_attr_nonnull
319 cx_attr_nonnull 313 CX_EXPORT int cxReallocate_(const CxAllocator *allocator, void **mem, size_t n);
320 cx_attr_export
321 int cxReallocate_(
322 const CxAllocator *allocator,
323 void **mem,
324 size_t n
325 );
326 314
327 /** 315 /**
328 * Reallocate a previously allocated block and changes the pointer in-place, 316 * Reallocate a previously allocated block and changes the pointer in-place,
329 * if necessary. 317 * if necessary.
330 * 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.
331 * 319 *
332 * @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.
333 * 321 *
334 * @par Error handling 322 * @par Error handling
335 * @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.
336 * 324 *
337 * @param allocator (@c CxAllocator*) the allocator 325 * @param allocator (@c CxAllocator*) the allocator
338 * @param mem (@c void**) pointer to the pointer to allocated block 326 * @param mem (@c void**) pointer to the pointer to allocated block
339 * @param n (@c size_t) the new size in bytes 327 * @param n (@c size_t) the new size in bytes
340 * @retval zero success 328 * @retval zero success
360 * @param nmemb the number of elements 348 * @param nmemb the number of elements
361 * @param size the size of each element 349 * @param size the size of each element
362 * @retval zero success 350 * @retval zero success
363 * @retval non-zero on failure 351 * @retval non-zero on failure
364 */ 352 */
365 cx_attr_nodiscard 353 cx_attr_nodiscard cx_attr_nonnull
366 cx_attr_nonnull 354 CX_EXPORT int cxReallocateArray_(const CxAllocator *allocator,
367 cx_attr_export 355 void **mem, size_t nmemb, size_t size);
368 int cxReallocateArray_(
369 const CxAllocator *allocator,
370 void **mem,
371 size_t nmemb,
372 size_t size
373 );
374 356
375 /** 357 /**
376 * Reallocate a previously allocated block and changes the pointer in-place, 358 * Reallocate a previously allocated block and changes the pointer in-place,
377 * if necessary. 359 * if necessary.
378 * This function acts like cxReallocArray() using the pointer pointed to 360 * This function acts like cxReallocArray() using the pointer pointed to
400 * @param allocator the allocator 382 * @param allocator the allocator
401 * @param nmemb the number of elements 383 * @param nmemb the number of elements
402 * @param size the size of each element in bytes 384 * @param size the size of each element in bytes
403 * @return a pointer to the allocated memory 385 * @return a pointer to the allocated memory
404 */ 386 */
405 cx_attr_nonnull_arg(1) 387 cx_attr_nonnull_arg(1) cx_attr_nodiscard
406 cx_attr_nodiscard 388 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2, 3)
407 cx_attr_malloc 389 CX_EXPORT void *cxCalloc(const CxAllocator *allocator, size_t nmemb, size_t size);
408 cx_attr_dealloc_ucx 390
409 cx_attr_allocsize(2, 3) 391 /**
410 cx_attr_export 392 * Allocate @p n bytes of memory and sets every byte to zero.
411 void *cxCalloc( 393 *
412 const CxAllocator *allocator, 394 * @param allocator the allocator
413 size_t nmemb, 395 * @param n the number of bytes
414 size_t size 396 * @return a pointer to the allocated memory
415 ); 397 */
398 cx_attr_nodiscard cx_attr_nonnull
399 cx_attr_malloc cx_attr_dealloc_ucx cx_attr_allocsize(2)
400 CX_EXPORT void *cxZalloc(const CxAllocator *allocator, size_t n);
401
402 /**
403 * Convenience macro that invokes cxMalloc() with the cxDefaultAllocator.
404 */
405 #define cxMallocDefault(...) cxMalloc(cxDefaultAllocator, __VA_ARGS__)
406 /**
407 * Convenience macro that invokes cxZalloc() with the cxDefaultAllocator.
408 */
409 #define cxZallocDefault(...) cxZalloc(cxDefaultAllocator, __VA_ARGS__)
410 /**
411 * Convenience macro that invokes cxCalloc() with the cxDefaultAllocator.
412 */
413 #define cxCallocDefault(...) cxCalloc(cxDefaultAllocator, __VA_ARGS__)
414 /**
415 * Convenience macro that invokes cxRealloc() with the cxDefaultAllocator.
416 */
417 #define cxReallocDefault(...) cxRealloc(cxDefaultAllocator, __VA_ARGS__)
418 /**
419 * Convenience macro that invokes cxReallocate() with the cxDefaultAllocator.
420 */
421 #define cxReallocateDefault(...) cxReallocate(cxDefaultAllocator, __VA_ARGS__)
422 /**
423 * Convenience macro that invokes cxReallocateArray() with the cxDefaultAllocator.
424 */
425 #define cxReallocateArrayDefault(...) cxReallocateArray(cxDefaultAllocator, __VA_ARGS__)
426 /**
427 * Convenience macro that invokes cxReallocArray() with the cxDefaultAllocator.
428 */
429 #define cxReallocArrayDefault(...) cxReallocArray(cxDefaultAllocator, __VA_ARGS__)
430 /**
431 * Convenience macro that invokes cxFree() with the cxDefaultAllocator.
432 */
433 #define cxFreeDefault(...) cxFree(cxDefaultAllocator, __VA_ARGS__)
416 434
417 #ifdef __cplusplus 435 #ifdef __cplusplus
418 } // extern "C" 436 } // extern "C"
419 #endif 437 #endif
420 438

Mercurial Repository: dav

mercurial