Mercurial > hg > ucx / file comparison

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

Mercurial Repository: ucx

mercurial