2 * Copyright © 2010 Intel Corporation
4 * Permission is hereby granted, free of charge, to any person obtaining a
5 * copy of this software and associated documentation files (the "Software"),
6 * to deal in the Software without restriction, including without limitation
7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
8 * and/or sell copies of the Software, and to permit persons to whom the
9 * Software is furnished to do so, subject to the following conditions:
11 * The above copyright notice and this permission notice (including the next
12 * paragraph) shall be included in all copies or substantial portions of the
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21 * DEALINGS IN THE SOFTWARE.
27 * ralloc: a recursive memory allocator
29 * The ralloc memory allocator creates a hierarchy of allocated
30 * objects. Every allocation is in reference to some parent, and
31 * every allocated object can in turn be used as the parent of a
32 * subsequent allocation. This allows for extremely convenient
33 * discarding of an entire tree/sub-tree of allocations by calling
34 * ralloc_free on any particular object to free it and all of its
37 * The conceptual working of ralloc was directly inspired by Andrew
38 * Tridgell's talloc, but ralloc is an independent implementation
39 * released under the MIT license and tuned for Mesa.
41 * talloc is more sophisticated than ralloc in that it includes reference
42 * counting and useful debugging features. However, it is released under
43 * a non-permissive open source license.
60 * \def ralloc(ctx, type)
61 * Allocate a new object chained off of the given context.
63 * This is equivalent to:
65 * ((type *) ralloc_size(ctx, sizeof(type))
68 #define ralloc(ctx, type) ((type *) ralloc_size(ctx, sizeof(type)))
71 * \def rzalloc(ctx, type)
72 * Allocate a new object out of the given context and initialize it to zero.
74 * This is equivalent to:
76 * ((type *) rzalloc_size(ctx, sizeof(type))
79 #define rzalloc(ctx, type) ((type *) rzalloc_size(ctx, sizeof(type)))
82 * Allocate a new ralloc context.
84 * While any ralloc'd pointer can be used as a context, sometimes it is useful
85 * to simply allocate a context with no associated memory.
87 * It is equivalent to:
89 * ((type *) ralloc_size(ctx, 0)
92 void *ralloc_context(const void *ctx
);
95 * Allocate memory chained off of the given context.
97 * This is the core allocation routine which is used by all others. It
98 * simply allocates storage for \p size bytes and returns the pointer,
99 * similar to \c malloc.
101 void *ralloc_size(const void *ctx
, size_t size
) MALLOCLIKE
;
104 * Allocate zero-initialized memory chained off of the given context.
106 * This is similar to \c calloc with a size of 1.
108 void *rzalloc_size(const void *ctx
, size_t size
) MALLOCLIKE
;
111 * Resize a piece of ralloc-managed memory, preserving data.
113 * Similar to \c realloc. Unlike C89, passing 0 for \p size does not free the
114 * memory. Instead, it resizes it to a 0-byte ralloc context, just like
115 * calling ralloc_size(ctx, 0). This is different from talloc.
117 * \param ctx The context to use for new allocation. If \p ptr != NULL,
118 * it must be the same as ralloc_parent(\p ptr).
119 * \param ptr Pointer to the memory to be resized. May be NULL.
120 * \param size The amount of memory to allocate, in bytes.
122 void *reralloc_size(const void *ctx
, void *ptr
, size_t size
);
124 /// \defgroup array Array Allocators @{
127 * \def ralloc_array(ctx, type, count)
128 * Allocate an array of objects chained off the given context.
130 * Similar to \c calloc, but does not initialize the memory to zero.
132 * More than a convenience function, this also checks for integer overflow when
133 * multiplying \c sizeof(type) and \p count. This is necessary for security.
135 * This is equivalent to:
137 * ((type *) ralloc_array_size(ctx, sizeof(type), count)
140 #define ralloc_array(ctx, type, count) \
141 ((type *) ralloc_array_size(ctx, sizeof(type), count))
144 * \def rzalloc_array(ctx, type, count)
145 * Allocate a zero-initialized array chained off the given context.
147 * Similar to \c calloc.
149 * More than a convenience function, this also checks for integer overflow when
150 * multiplying \c sizeof(type) and \p count. This is necessary for security.
152 * This is equivalent to:
154 * ((type *) rzalloc_array_size(ctx, sizeof(type), count)
157 #define rzalloc_array(ctx, type, count) \
158 ((type *) rzalloc_array_size(ctx, sizeof(type), count))
161 * \def reralloc(ctx, ptr, type, count)
162 * Resize a ralloc-managed array, preserving data.
164 * Similar to \c realloc. Unlike C89, passing 0 for \p size does not free the
165 * memory. Instead, it resizes it to a 0-byte ralloc context, just like
166 * calling ralloc_size(ctx, 0). This is different from talloc.
168 * More than a convenience function, this also checks for integer overflow when
169 * multiplying \c sizeof(type) and \p count. This is necessary for security.
171 * \param ctx The context to use for new allocation. If \p ptr != NULL,
172 * it must be the same as ralloc_parent(\p ptr).
173 * \param ptr Pointer to the array to be resized. May be NULL.
174 * \param type The element type.
175 * \param count The number of elements to allocate.
177 #define reralloc(ctx, ptr, type, count) \
178 ((type *) reralloc_array_size(ctx, ptr, sizeof(type), count))
181 * Allocate memory for an array chained off the given context.
183 * Similar to \c calloc, but does not initialize the memory to zero.
185 * More than a convenience function, this also checks for integer overflow when
186 * multiplying \p size and \p count. This is necessary for security.
188 void *ralloc_array_size(const void *ctx
, size_t size
, unsigned count
) MALLOCLIKE
;
191 * Allocate a zero-initialized array chained off the given context.
193 * Similar to \c calloc.
195 * More than a convenience function, this also checks for integer overflow when
196 * multiplying \p size and \p count. This is necessary for security.
198 void *rzalloc_array_size(const void *ctx
, size_t size
, unsigned count
) MALLOCLIKE
;
201 * Resize a ralloc-managed array, preserving data.
203 * Similar to \c realloc. Unlike C89, passing 0 for \p size does not free the
204 * memory. Instead, it resizes it to a 0-byte ralloc context, just like
205 * calling ralloc_size(ctx, 0). This is different from talloc.
207 * More than a convenience function, this also checks for integer overflow when
208 * multiplying \c sizeof(type) and \p count. This is necessary for security.
210 * \param ctx The context to use for new allocation. If \p ptr != NULL,
211 * it must be the same as ralloc_parent(\p ptr).
212 * \param ptr Pointer to the array to be resized. May be NULL.
213 * \param size The size of an individual element.
214 * \param count The number of elements to allocate.
216 * \return True unless allocation failed.
218 void *reralloc_array_size(const void *ctx
, void *ptr
, size_t size
,
223 * Free a piece of ralloc-managed memory.
225 * This will also free the memory of any children allocated this context.
227 void ralloc_free(void *ptr
);
230 * "Steal" memory from one context, changing it to another.
232 * This changes \p ptr's context to \p new_ctx. This is quite useful if
233 * memory is allocated out of a temporary context.
235 void ralloc_steal(const void *new_ctx
, void *ptr
);
238 * Reparent all children from one context to another.
240 * This effectively calls ralloc_steal(new_ctx, child) for all children of \p old_ctx.
242 void ralloc_adopt(const void *new_ctx
, void *old_ctx
);
245 * Return the given pointer's ralloc context.
247 void *ralloc_parent(const void *ptr
);
250 * Set a callback to occur just before an object is freed.
252 void ralloc_set_destructor(const void *ptr
, void(*destructor
)(void *));
254 /// \defgroup array String Functions @{
256 * Duplicate a string, allocating the memory from the given context.
258 char *ralloc_strdup(const void *ctx
, const char *str
) MALLOCLIKE
;
261 * Duplicate a string, allocating the memory from the given context.
263 * Like \c strndup, at most \p n characters are copied. If \p str is longer
264 * than \p n characters, \p n are copied, and a termining \c '\0' byte is added.
266 char *ralloc_strndup(const void *ctx
, const char *str
, size_t n
) MALLOCLIKE
;
269 * Concatenate two strings, allocating the necessary space.
271 * This appends \p str to \p *dest, similar to \c strcat, using ralloc_resize
272 * to expand \p *dest to the appropriate size. \p dest will be updated to the
273 * new pointer unless allocation fails.
275 * The result will always be null-terminated.
277 * \return True unless allocation failed.
279 bool ralloc_strcat(char **dest
, const char *str
);
282 * Concatenate two strings, allocating the necessary space.
284 * This appends at most \p n bytes of \p str to \p *dest, using ralloc_resize
285 * to expand \p *dest to the appropriate size. \p dest will be updated to the
286 * new pointer unless allocation fails.
288 * The result will always be null-terminated; \p str does not need to be null
289 * terminated if it is longer than \p n.
291 * \return True unless allocation failed.
293 bool ralloc_strncat(char **dest
, const char *str
, size_t n
);
298 * This is analogous to \c sprintf, but allocates enough space (using \p ctx
299 * as the context) for the resulting string.
301 * \return The newly allocated string.
303 char *ralloc_asprintf (const void *ctx
, const char *fmt
, ...) PRINTFLIKE(2, 3) MALLOCLIKE
;
306 * Print to a string, given a va_list.
308 * This is analogous to \c vsprintf, but allocates enough space (using \p ctx
309 * as the context) for the resulting string.
311 * \return The newly allocated string.
313 char *ralloc_vasprintf(const void *ctx
, const char *fmt
, va_list args
) MALLOCLIKE
;
316 * Rewrite the tail of an existing string, starting at a given index.
318 * Overwrites the contents of *str starting at \p start with newly formatted
319 * text, including a new null-terminator. Allocates more memory as necessary.
321 * This can be used to append formatted text when the length of the existing
322 * string is already known, saving a strlen() call.
324 * \sa ralloc_asprintf_append
326 * \param str The string to be updated.
327 * \param start The index to start appending new data at.
328 * \param fmt A printf-style formatting string
330 * \p str will be updated to the new pointer unless allocation fails.
331 * \p start will be increased by the length of the newly formatted text.
333 * \return True unless allocation failed.
335 bool ralloc_asprintf_rewrite_tail(char **str
, size_t *start
,
336 const char *fmt
, ...)
340 * Rewrite the tail of an existing string, starting at a given index.
342 * Overwrites the contents of *str starting at \p start with newly formatted
343 * text, including a new null-terminator. Allocates more memory as necessary.
345 * This can be used to append formatted text when the length of the existing
346 * string is already known, saving a strlen() call.
348 * \sa ralloc_vasprintf_append
350 * \param str The string to be updated.
351 * \param start The index to start appending new data at.
352 * \param fmt A printf-style formatting string
353 * \param args A va_list containing the data to be formatted
355 * \p str will be updated to the new pointer unless allocation fails.
356 * \p start will be increased by the length of the newly formatted text.
358 * \return True unless allocation failed.
360 bool ralloc_vasprintf_rewrite_tail(char **str
, size_t *start
, const char *fmt
,
364 * Append formatted text to the supplied string.
366 * This is equivalent to
368 * ralloc_asprintf_rewrite_tail(str, strlen(*str), fmt, ...)
371 * \sa ralloc_asprintf
372 * \sa ralloc_asprintf_rewrite_tail
375 * \p str will be updated to the new pointer unless allocation fails.
377 * \return True unless allocation failed.
379 bool ralloc_asprintf_append (char **str
, const char *fmt
, ...)
383 * Append formatted text to the supplied string, given a va_list.
385 * This is equivalent to
387 * ralloc_vasprintf_rewrite_tail(str, strlen(*str), fmt, args)
390 * \sa ralloc_vasprintf
391 * \sa ralloc_vasprintf_rewrite_tail
394 * \p str will be updated to the new pointer unless allocation fails.
396 * \return True unless allocation failed.
398 bool ralloc_vasprintf_append(char **str
, const char *fmt
, va_list args
);
402 * Declare C++ new and delete operators which use ralloc.
404 * Placing this macro in the body of a class makes it possible to do:
406 * TYPE *var = new(mem_ctx) TYPE(...);
409 * which is more idiomatic in C++ than calling ralloc.
411 #define DECLARE_ALLOC_CXX_OPERATORS_TEMPLATE(TYPE, ALLOC_FUNC) \
413 static void _ralloc_destructor(void *p) \
415 reinterpret_cast<TYPE *>(p)->~TYPE(); \
418 static void* operator new(size_t size, void *mem_ctx) \
420 void *p = ALLOC_FUNC(mem_ctx, size); \
422 if (!HAS_TRIVIAL_DESTRUCTOR(TYPE)) \
423 ralloc_set_destructor(p, _ralloc_destructor); \
427 static void operator delete(void *p) \
429 /* The object's destructor is guaranteed to have already been \
430 * called by the delete operator at this point -- Make sure it's \
431 * not called again. \
433 if (!HAS_TRIVIAL_DESTRUCTOR(TYPE)) \
434 ralloc_set_destructor(p, NULL); \
438 #define DECLARE_RALLOC_CXX_OPERATORS(type) \
439 DECLARE_ALLOC_CXX_OPERATORS_TEMPLATE(type, ralloc_size)
441 #define DECLARE_RZALLOC_CXX_OPERATORS(type) \
442 DECLARE_ALLOC_CXX_OPERATORS_TEMPLATE(type, rzalloc_size)
444 #define DECLARE_LINEAR_ALLOC_CXX_OPERATORS(type) \
445 DECLARE_ALLOC_CXX_OPERATORS_TEMPLATE(type, linear_alloc_child)
447 #define DECLARE_LINEAR_ZALLOC_CXX_OPERATORS(type) \
448 DECLARE_ALLOC_CXX_OPERATORS_TEMPLATE(type, linear_zalloc_child)
452 * Do a fast allocation from the linear buffer, also known as the child node
453 * from the allocator's point of view. It can't be freed directly. You have
454 * to free the parent or the ralloc parent.
456 * \param parent parent node of the linear allocator
457 * \param size size to allocate (max 32 bits)
459 void *linear_alloc_child(void *parent
, unsigned size
);
462 * Allocate a parent node that will hold linear buffers. The returned
463 * allocation is actually the first child node, but it's also the handle
464 * of the parent node. Use it for all child node allocations.
466 * \param ralloc_ctx ralloc context, must not be NULL
467 * \param size size to allocate (max 32 bits)
469 void *linear_alloc_parent(void *ralloc_ctx
, unsigned size
);
472 * Same as linear_alloc_child, but also clears memory.
474 void *linear_zalloc_child(void *parent
, unsigned size
);
477 * Same as linear_alloc_parent, but also clears memory.
479 void *linear_zalloc_parent(void *ralloc_ctx
, unsigned size
);
482 * Free the linear parent node. This will free all child nodes too.
483 * Freeing the ralloc parent will also free this.
485 void linear_free_parent(void *ptr
);
488 * Same as ralloc_steal, but steals the linear parent node.
490 void ralloc_steal_linear_parent(void *new_ralloc_ctx
, void *ptr
);
493 * Return the ralloc parent of the linear parent node.
495 void *ralloc_parent_of_linear_parent(void *ptr
);
498 * Same as realloc except that the linear allocator doesn't free child nodes,
499 * so it's reduced to memory duplication. It's used in places where
500 * reallocation is required. Don't use it often. It's much slower than
503 void *linear_realloc(void *parent
, void *old
, unsigned new_size
);
505 /* The functions below have the same semantics as their ralloc counterparts,
506 * except that they always allocate a linear child node.
508 char *linear_strdup(void *parent
, const char *str
);
509 char *linear_asprintf(void *parent
, const char *fmt
, ...);
510 char *linear_vasprintf(void *parent
, const char *fmt
, va_list args
);
511 bool linear_asprintf_append(void *parent
, char **str
, const char *fmt
, ...);
512 bool linear_vasprintf_append(void *parent
, char **str
, const char *fmt
,
514 bool linear_asprintf_rewrite_tail(void *parent
, char **str
, size_t *start
,
515 const char *fmt
, ...);
516 bool linear_vasprintf_rewrite_tail(void *parent
, char **str
, size_t *start
,
517 const char *fmt
, va_list args
);
518 bool linear_strcat(void *parent
, char **dest
, const char *str
);
521 } /* end of extern "C" */