workbench/libs/mesa/src/glsl/ralloc.h

   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 <stddef.h>
  55 #include <stdarg.h>
  56 #ifndef __cplusplus
  57 #include <stdbool.h>
  58 #endif
  59
  60 /**
  61  * \def ralloc(ctx, type)
  62  * Allocate a new object chained off of the given context.
  63  *
  64  * This is equivalent to:
  65  * \code
  66  * ((type *) ralloc_size(ctx, sizeof(type))
  67  * \endcode
  68  */
  69 #define ralloc(ctx, type)  ((type *) ralloc_size(ctx, sizeof(type)))
  70
  71 /**
  72  * \def rzalloc(ctx, type)
  73  * Allocate a new object out of the given context and initialize it to zero.
  74  *
  75  * This is equivalent to:
  76  * \code
  77  * ((type *) rzalloc_size(ctx, sizeof(type))
  78  * \endcode
  79  */
  80 #define rzalloc(ctx, type) ((type *) rzalloc_size(ctx, sizeof(type)))
  81
  82 /**
  83  * Allocate a new ralloc context.
  84  *
  85  * While any ralloc'd pointer can be used as a context, sometimes it is useful
  86  * to simply allocate a context with no associated memory.
  87  *
  88  * It is equivalent to:
  89  * \code
  90  * ((type *) ralloc_size(ctx, 0)
  91  * \endcode
  92  */
  93 void *ralloc_context(const void *ctx);
  94
  95 /**
  96  * Allocate memory chained off of the given context.
  97  *
  98  * This is the core allocation routine which is used by all others.  It
  99  * simply allocates storage for \p size bytes and returns the pointer,
 100  * similar to \c malloc.
 101  */
 102 void *ralloc_size(const void *ctx, size_t size);
 103
 104 /**
 105  * Allocate zero-initialized memory chained off of the given context.
 106  *
 107  * This is similar to \c calloc with a size of 1.
 108  */
 109 void *rzalloc_size(const void *ctx, size_t size);
 110
 111 /**
 112  * Resize a piece of ralloc-managed memory, preserving data.
 113  *
 114  * Similar to \c realloc.  Unlike C89, passing 0 for \p size does not free the
 115  * memory.  Instead, it resizes it to a 0-byte ralloc context, just like
 116  * calling ralloc_size(ctx, 0).  This is different from talloc.
 117  *
 118  * \param ctx  The context to use for new allocation.  If \p ptr != NULL,
 119  *             it must be the same as ralloc_parent(\p ptr).
 120  * \param ptr  Pointer to the memory to be resized.  May be NULL.
 121  * \param size The amount of memory to allocate, in bytes.
 122  */
 123 void *reralloc_size(const void *ctx, void *ptr, size_t size);
 124
 125 /// \defgroup array Array Allocators @{
 126
 127 /**
 128  * \def ralloc_array(ctx, type, count)
 129  * Allocate an array of objects chained off the given context.
 130  *
 131  * Similar to \c calloc, but does not initialize the memory to zero.
 132  *
 133  * More than a convenience function, this also checks for integer overflow when
 134  * multiplying \c sizeof(type) and \p count.  This is necessary for security.
 135  *
 136  * This is equivalent to:
 137  * \code
 138  * ((type *) ralloc_array_size(ctx, sizeof(type), count)
 139  * \endcode
 140  */
 141 #define ralloc_array(ctx, type, count) \
 142    ((type *) ralloc_array_size(ctx, sizeof(type), count))
 143
 144 /**
 145  * \def rzalloc_array(ctx, type, count)
 146  * Allocate a zero-initialized array chained off the given context.
 147  *
 148  * Similar to \c calloc.
 149  *
 150  * More than a convenience function, this also checks for integer overflow when
 151  * multiplying \c sizeof(type) and \p count.  This is necessary for security.
 152  *
 153  * This is equivalent to:
 154  * \code
 155  * ((type *) rzalloc_array_size(ctx, sizeof(type), count)
 156  * \endcode
 157  */
 158 #define rzalloc_array(ctx, type, count) \
 159    ((type *) rzalloc_array_size(ctx, sizeof(type), count))
 160
 161 /**
 162  * \def reralloc(ctx, ptr, type, count)
 163  * Resize a ralloc-managed array, preserving data.
 164  *
 165  * Similar to \c realloc.  Unlike C89, passing 0 for \p size does not free the
 166  * memory.  Instead, it resizes it to a 0-byte ralloc context, just like
 167  * calling ralloc_size(ctx, 0).  This is different from talloc.
 168  *
 169  * More than a convenience function, this also checks for integer overflow when
 170  * multiplying \c sizeof(type) and \p count.  This is necessary for security.
 171  *
 172  * \param ctx   The context to use for new allocation.  If \p ptr != NULL,
 173  *              it must be the same as ralloc_parent(\p ptr).
 174  * \param ptr   Pointer to the array to be resized.  May be NULL.
 175  * \param type  The element type.
 176  * \param count The number of elements to allocate.
 177  */
 178 #define reralloc(ctx, ptr, type, count) \
 179    ((type *) reralloc_array_size(ctx, ptr, sizeof(type), count))
 180
 181 /**
 182  * Allocate memory for an array chained off the given context.
 183  *
 184  * Similar to \c calloc, but does not initialize the memory to zero.
 185  *
 186  * More than a convenience function, this also checks for integer overflow when
 187  * multiplying \p size and \p count.  This is necessary for security.
 188  */
 189 void *ralloc_array_size(const void *ctx, size_t size, unsigned count);
 190
 191 /**
 192  * Allocate a zero-initialized array chained off the given context.
 193  *
 194  * Similar to \c calloc.
 195  *
 196  * More than a convenience function, this also checks for integer overflow when
 197  * multiplying \p size and \p count.  This is necessary for security.
 198  */
 199 void *rzalloc_array_size(const void *ctx, size_t size, unsigned count);
 200
 201 /**
 202  * Resize a ralloc-managed array, preserving data.
 203  *
 204  * Similar to \c realloc.  Unlike C89, passing 0 for \p size does not free the
 205  * memory.  Instead, it resizes it to a 0-byte ralloc context, just like
 206  * calling ralloc_size(ctx, 0).  This is different from talloc.
 207  *
 208  * More than a convenience function, this also checks for integer overflow when
 209  * multiplying \c sizeof(type) and \p count.  This is necessary for security.
 210  *
 211  * \param ctx   The context to use for new allocation.  If \p ptr != NULL,
 212  *              it must be the same as ralloc_parent(\p ptr).
 213  * \param ptr   Pointer to the array to be resized.  May be NULL.
 214  * \param size  The size of an individual element.
 215  * \param count The number of elements to allocate.
 216  *
 217  * \return True unless allocation failed.
 218  */
 219 void *reralloc_array_size(const void *ctx, void *ptr, size_t size,
 220                           unsigned count);
 221 /// @}
 222
 223 /**
 224  * Free a piece of ralloc-managed memory.
 225  *
 226  * This will also free the memory of any children allocated this context.
 227  */
 228 void ralloc_free(void *ptr);
 229
 230 /**
 231  * "Steal" memory from one context, changing it to another.
 232  *
 233  * This changes \p ptr's context to \p new_ctx.  This is quite useful if
 234  * memory is allocated out of a temporary context.
 235  */
 236 void ralloc_steal(const void *new_ctx, void *ptr);
 237
 238 /**
 239  * Return the given pointer's ralloc context.
 240  */
 241 void *ralloc_parent(const void *ptr);
 242
 243 /**
 244  * Return a context whose memory will be automatically freed at program exit.
 245  *
 246  * The first call to this function creates a context and registers a handler
 247  * to free it using \c atexit.  This may cause trouble if used in a library
 248  * loaded with \c dlopen.
 249  */
 250 void *ralloc_autofree_context(void);
 251
 252 /**
 253  * Set a callback to occur just before an object is freed.
 254  */
 255 void ralloc_set_destructor(const void *ptr, void(*destructor)(void *));
 256
 257 /// \defgroup array String Functions @{
 258 /**
 259  * Duplicate a string, allocating the memory from the given context.
 260  */
 261 char *ralloc_strdup(const void *ctx, const char *str);
 262
 263 /**
 264  * Duplicate a string, allocating the memory from the given context.
 265  *
 266  * Like \c strndup, at most \p n characters are copied.  If \p str is longer
 267  * than \p n characters, \p n are copied, and a termining \c '\0' byte is added.
 268  */
 269 char *ralloc_strndup(const void *ctx, const char *str, size_t n);
 270
 271 /**
 272  * Concatenate two strings, allocating the necessary space.
 273  *
 274  * This appends \p str to \p *dest, similar to \c strcat, using ralloc_resize
 275  * to expand \p *dest to the appropriate size.  \p dest will be updated to the
 276  * new pointer unless allocation fails.
 277  *
 278  * The result will always be null-terminated.
 279  *
 280  * \return True unless allocation failed.
 281  */
 282 bool ralloc_strcat(char **dest, const char *str);
 283
 284 /**
 285  * Concatenate two strings, allocating the necessary space.
 286  *
 287  * This appends at most \p n bytes of \p str to \p *dest, using ralloc_resize
 288  * to expand \p *dest to the appropriate size.  \p dest will be updated to the
 289  * new pointer unless allocation fails.
 290  *
 291  * The result will always be null-terminated; \p str does not need to be null
 292  * terminated if it is longer than \p n.
 293  *
 294  * \return True unless allocation failed.
 295  */
 296 bool ralloc_strncat(char **dest, const char *str, size_t n);
 297
 298 /**
 299  * Print to a string.
 300  *
 301  * This is analogous to \c sprintf, but allocates enough space (using \p ctx
 302  * as the context) for the resulting string.
 303  *
 304  * \return The newly allocated string.
 305  */
 306 char *ralloc_asprintf (const void *ctx, const char *fmt, ...);
 307
 308 /**
 309  * Print to a string, given a va_list.
 310  *
 311  * This is analogous to \c vsprintf, but allocates enough space (using \p ctx
 312  * as the context) for the resulting string.
 313  *
 314  * \return The newly allocated string.
 315  */
 316 char *ralloc_vasprintf(const void *ctx, const char *fmt, va_list args);
 317
 318 /**
 319  * Append formatted text to the supplied string.
 320  *
 321  * \sa ralloc_asprintf
 322  * \sa ralloc_strcat
 323  *
 324  * \p str will be updated to the new pointer unless allocation fails.
 325  *
 326  * \return True unless allocation failed.
 327  */
 328 bool ralloc_asprintf_append (char **str, const char *fmt, ...);
 329
 330 /**
 331  * Append formatted text to the supplied string, given a va_list.
 332  *
 333  * \sa ralloc_vasprintf
 334  * \sa ralloc_strcat
 335  *
 336  * \p str will be updated to the new pointer unless allocation fails.
 337  *
 338  * \return True unless allocation failed.
 339  */
 340 bool ralloc_vasprintf_append(char **str, const char *fmt, va_list args);
 341 /// @}
 342
 343 #ifdef __cplusplus
 344 } /* end of extern "C" */
 345 #endif
 346
 347 #endif