Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
4358 | Serge | 1 | /* |
2 | * Copyright © 2010 Intel Corporation |
||
3 | * |
||
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: |
||
10 | * |
||
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 |
||
13 | * Software. |
||
14 | * |
||
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. |
||
22 | */ |
||
23 | |||
24 | /** |
||
25 | * \file ralloc.h |
||
26 | * |
||
27 | * ralloc: a recursive memory allocator |
||
28 | * |
||
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 |
||
35 | * children. |
||
36 | * |
||
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. |
||
40 | * |
||
41 | * The talloc implementation is available under the GNU Lesser |
||
42 | * General Public License (GNU LGPL), version 3 or later. It is |
||
43 | * more sophisticated than ralloc in that it includes reference |
||
44 | * counting and debugging features. See: http://talloc.samba.org/ |
||
45 | */ |
||
46 | |||
47 | #ifndef RALLOC_H |
||
48 | #define RALLOC_H |
||
49 | |||
50 | #ifdef __cplusplus |
||
51 | extern "C" { |
||
52 | #endif |
||
53 | |||
54 | #include |
||
55 | #include |
||
56 | #include |
||
57 | #include "main/compiler.h" |
||
58 | |||
59 | /** |
||
60 | * \def ralloc(ctx, type) |
||
61 | * Allocate a new object chained off of the given context. |
||
62 | * |
||
63 | * This is equivalent to: |
||
64 | * \code |
||
65 | * ((type *) ralloc_size(ctx, sizeof(type)) |
||
66 | * \endcode |
||
67 | */ |
||
68 | #define ralloc(ctx, type) ((type *) ralloc_size(ctx, sizeof(type))) |
||
69 | |||
70 | /** |
||
71 | * \def rzalloc(ctx, type) |
||
72 | * Allocate a new object out of the given context and initialize it to zero. |
||
73 | * |
||
74 | * This is equivalent to: |
||
75 | * \code |
||
76 | * ((type *) rzalloc_size(ctx, sizeof(type)) |
||
77 | * \endcode |
||
78 | */ |
||
79 | #define rzalloc(ctx, type) ((type *) rzalloc_size(ctx, sizeof(type))) |
||
80 | |||
81 | /** |
||
82 | * Allocate a new ralloc context. |
||
83 | * |
||
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. |
||
86 | * |
||
87 | * It is equivalent to: |
||
88 | * \code |
||
89 | * ((type *) ralloc_size(ctx, 0) |
||
90 | * \endcode |
||
91 | */ |
||
92 | void *ralloc_context(const void *ctx); |
||
93 | |||
94 | /** |
||
95 | * Allocate memory chained off of the given context. |
||
96 | * |
||
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. |
||
100 | */ |
||
101 | void *ralloc_size(const void *ctx, size_t size); |
||
102 | |||
103 | /** |
||
104 | * Allocate zero-initialized memory chained off of the given context. |
||
105 | * |
||
106 | * This is similar to \c calloc with a size of 1. |
||
107 | */ |
||
108 | void *rzalloc_size(const void *ctx, size_t size); |
||
109 | |||
110 | /** |
||
111 | * Resize a piece of ralloc-managed memory, preserving data. |
||
112 | * |
||
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. |
||
116 | * |
||
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. |
||
121 | */ |
||
122 | void *reralloc_size(const void *ctx, void *ptr, size_t size); |
||
123 | |||
124 | /// \defgroup array Array Allocators @{ |
||
125 | |||
126 | /** |
||
127 | * \def ralloc_array(ctx, type, count) |
||
128 | * Allocate an array of objects chained off the given context. |
||
129 | * |
||
130 | * Similar to \c calloc, but does not initialize the memory to zero. |
||
131 | * |
||
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. |
||
134 | * |
||
135 | * This is equivalent to: |
||
136 | * \code |
||
137 | * ((type *) ralloc_array_size(ctx, sizeof(type), count) |
||
138 | * \endcode |
||
139 | */ |
||
140 | #define ralloc_array(ctx, type, count) \ |
||
141 | ((type *) ralloc_array_size(ctx, sizeof(type), count)) |
||
142 | |||
143 | /** |
||
144 | * \def rzalloc_array(ctx, type, count) |
||
145 | * Allocate a zero-initialized array chained off the given context. |
||
146 | * |
||
147 | * Similar to \c calloc. |
||
148 | * |
||
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. |
||
151 | * |
||
152 | * This is equivalent to: |
||
153 | * \code |
||
154 | * ((type *) rzalloc_array_size(ctx, sizeof(type), count) |
||
155 | * \endcode |
||
156 | */ |
||
157 | #define rzalloc_array(ctx, type, count) \ |
||
158 | ((type *) rzalloc_array_size(ctx, sizeof(type), count)) |
||
159 | |||
160 | /** |
||
161 | * \def reralloc(ctx, ptr, type, count) |
||
162 | * Resize a ralloc-managed array, preserving data. |
||
163 | * |
||
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. |
||
167 | * |
||
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. |
||
170 | * |
||
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. |
||
176 | */ |
||
177 | #define reralloc(ctx, ptr, type, count) \ |
||
178 | ((type *) reralloc_array_size(ctx, ptr, sizeof(type), count)) |
||
179 | |||
180 | /** |
||
181 | * Allocate memory for an array chained off the given context. |
||
182 | * |
||
183 | * Similar to \c calloc, but does not initialize the memory to zero. |
||
184 | * |
||
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. |
||
187 | */ |
||
188 | void *ralloc_array_size(const void *ctx, size_t size, unsigned count); |
||
189 | |||
190 | /** |
||
191 | * Allocate a zero-initialized array chained off the given context. |
||
192 | * |
||
193 | * Similar to \c calloc. |
||
194 | * |
||
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. |
||
197 | */ |
||
198 | void *rzalloc_array_size(const void *ctx, size_t size, unsigned count); |
||
199 | |||
200 | /** |
||
201 | * Resize a ralloc-managed array, preserving data. |
||
202 | * |
||
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. |
||
206 | * |
||
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. |
||
209 | * |
||
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. |
||
215 | * |
||
216 | * \return True unless allocation failed. |
||
217 | */ |
||
218 | void *reralloc_array_size(const void *ctx, void *ptr, size_t size, |
||
219 | unsigned count); |
||
220 | /// @} |
||
221 | |||
222 | /** |
||
223 | * Free a piece of ralloc-managed memory. |
||
224 | * |
||
225 | * This will also free the memory of any children allocated this context. |
||
226 | */ |
||
227 | void ralloc_free(void *ptr); |
||
228 | |||
229 | /** |
||
230 | * "Steal" memory from one context, changing it to another. |
||
231 | * |
||
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. |
||
234 | */ |
||
235 | void ralloc_steal(const void *new_ctx, void *ptr); |
||
236 | |||
237 | /** |
||
238 | * Return the given pointer's ralloc context. |
||
239 | */ |
||
240 | void *ralloc_parent(const void *ptr); |
||
241 | |||
242 | /** |
||
243 | * Return a context whose memory will be automatically freed at program exit. |
||
244 | * |
||
245 | * The first call to this function creates a context and registers a handler |
||
246 | * to free it using \c atexit. This may cause trouble if used in a library |
||
247 | * loaded with \c dlopen. |
||
248 | */ |
||
249 | void *ralloc_autofree_context(void); |
||
250 | |||
251 | /** |
||
252 | * Set a callback to occur just before an object is freed. |
||
253 | */ |
||
254 | void ralloc_set_destructor(const void *ptr, void(*destructor)(void *)); |
||
255 | |||
256 | /// \defgroup array String Functions @{ |
||
257 | /** |
||
258 | * Duplicate a string, allocating the memory from the given context. |
||
259 | */ |
||
260 | char *ralloc_strdup(const void *ctx, const char *str); |
||
261 | |||
262 | /** |
||
263 | * Duplicate a string, allocating the memory from the given context. |
||
264 | * |
||
265 | * Like \c strndup, at most \p n characters are copied. If \p str is longer |
||
266 | * than \p n characters, \p n are copied, and a termining \c '\0' byte is added. |
||
267 | */ |
||
268 | char *ralloc_strndup(const void *ctx, const char *str, size_t n); |
||
269 | |||
270 | /** |
||
271 | * Concatenate two strings, allocating the necessary space. |
||
272 | * |
||
273 | * This appends \p str to \p *dest, similar to \c strcat, using ralloc_resize |
||
274 | * to expand \p *dest to the appropriate size. \p dest will be updated to the |
||
275 | * new pointer unless allocation fails. |
||
276 | * |
||
277 | * The result will always be null-terminated. |
||
278 | * |
||
279 | * \return True unless allocation failed. |
||
280 | */ |
||
281 | bool ralloc_strcat(char **dest, const char *str); |
||
282 | |||
283 | /** |
||
284 | * Concatenate two strings, allocating the necessary space. |
||
285 | * |
||
286 | * This appends at most \p n bytes of \p str to \p *dest, using ralloc_resize |
||
287 | * to expand \p *dest to the appropriate size. \p dest will be updated to the |
||
288 | * new pointer unless allocation fails. |
||
289 | * |
||
290 | * The result will always be null-terminated; \p str does not need to be null |
||
291 | * terminated if it is longer than \p n. |
||
292 | * |
||
293 | * \return True unless allocation failed. |
||
294 | */ |
||
295 | bool ralloc_strncat(char **dest, const char *str, size_t n); |
||
296 | |||
297 | /** |
||
298 | * Print to a string. |
||
299 | * |
||
300 | * This is analogous to \c sprintf, but allocates enough space (using \p ctx |
||
301 | * as the context) for the resulting string. |
||
302 | * |
||
303 | * \return The newly allocated string. |
||
304 | */ |
||
305 | char *ralloc_asprintf (const void *ctx, const char *fmt, ...) PRINTFLIKE(2, 3); |
||
306 | |||
307 | /** |
||
308 | * Print to a string, given a va_list. |
||
309 | * |
||
310 | * This is analogous to \c vsprintf, but allocates enough space (using \p ctx |
||
311 | * as the context) for the resulting string. |
||
312 | * |
||
313 | * \return The newly allocated string. |
||
314 | */ |
||
315 | char *ralloc_vasprintf(const void *ctx, const char *fmt, va_list args); |
||
316 | |||
317 | /** |
||
318 | * Rewrite the tail of an existing string, starting at a given index. |
||
319 | * |
||
320 | * Overwrites the contents of *str starting at \p start with newly formatted |
||
321 | * text, including a new null-terminator. Allocates more memory as necessary. |
||
322 | * |
||
323 | * This can be used to append formatted text when the length of the existing |
||
324 | * string is already known, saving a strlen() call. |
||
325 | * |
||
326 | * \sa ralloc_asprintf_append |
||
327 | * |
||
328 | * \param str The string to be updated. |
||
329 | * \param start The index to start appending new data at. |
||
330 | * \param fmt A printf-style formatting string |
||
331 | * |
||
332 | * \p str will be updated to the new pointer unless allocation fails. |
||
333 | * \p start will be increased by the length of the newly formatted text. |
||
334 | * |
||
335 | * \return True unless allocation failed. |
||
336 | */ |
||
337 | bool ralloc_asprintf_rewrite_tail(char **str, size_t *start, |
||
338 | const char *fmt, ...) |
||
339 | PRINTFLIKE(3, 4); |
||
340 | |||
341 | /** |
||
342 | * Rewrite the tail of an existing string, starting at a given index. |
||
343 | * |
||
344 | * Overwrites the contents of *str starting at \p start with newly formatted |
||
345 | * text, including a new null-terminator. Allocates more memory as necessary. |
||
346 | * |
||
347 | * This can be used to append formatted text when the length of the existing |
||
348 | * string is already known, saving a strlen() call. |
||
349 | * |
||
350 | * \sa ralloc_vasprintf_append |
||
351 | * |
||
352 | * \param str The string to be updated. |
||
353 | * \param start The index to start appending new data at. |
||
354 | * \param fmt A printf-style formatting string |
||
355 | * \param args A va_list containing the data to be formatted |
||
356 | * |
||
357 | * \p str will be updated to the new pointer unless allocation fails. |
||
358 | * \p start will be increased by the length of the newly formatted text. |
||
359 | * |
||
360 | * \return True unless allocation failed. |
||
361 | */ |
||
362 | bool ralloc_vasprintf_rewrite_tail(char **str, size_t *start, const char *fmt, |
||
363 | va_list args); |
||
364 | |||
365 | /** |
||
366 | * Append formatted text to the supplied string. |
||
367 | * |
||
368 | * This is equivalent to |
||
369 | * \code |
||
370 | * ralloc_asprintf_rewrite_tail(str, strlen(*str), fmt, ...) |
||
371 | * \endcode |
||
372 | * |
||
373 | * \sa ralloc_asprintf |
||
374 | * \sa ralloc_asprintf_rewrite_tail |
||
375 | * \sa ralloc_strcat |
||
376 | * |
||
377 | * \p str will be updated to the new pointer unless allocation fails. |
||
378 | * |
||
379 | * \return True unless allocation failed. |
||
380 | */ |
||
381 | bool ralloc_asprintf_append (char **str, const char *fmt, ...) |
||
382 | PRINTFLIKE(2, 3); |
||
383 | |||
384 | /** |
||
385 | * Append formatted text to the supplied string, given a va_list. |
||
386 | * |
||
387 | * This is equivalent to |
||
388 | * \code |
||
389 | * ralloc_vasprintf_rewrite_tail(str, strlen(*str), fmt, args) |
||
390 | * \endcode |
||
391 | * |
||
392 | * \sa ralloc_vasprintf |
||
393 | * \sa ralloc_vasprintf_rewrite_tail |
||
394 | * \sa ralloc_strcat |
||
395 | * |
||
396 | * \p str will be updated to the new pointer unless allocation fails. |
||
397 | * |
||
398 | * \return True unless allocation failed. |
||
399 | */ |
||
400 | bool ralloc_vasprintf_append(char **str, const char *fmt, va_list args); |
||
401 | /// @} |
||
402 | |||
403 | #ifdef __cplusplus |
||
404 | } /* end of extern "C" */ |
||
405 | #endif |
||
406 | |||
407 | #endif |