docs/reference/glib/tmpl/memory.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Memory Allocation
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 general memory-handling.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These functions provide support for allocating and freeing memory.
  10 </para>
  11 <note>
  12 <para>
  13 If any call to allocate memory fails, the application is terminated.
  14 This also means that there is no need to check if the call succeeded.
  15 </para>
  16 </note>
  17
  18 <!-- ##### SECTION See_Also ##### -->
  19 <para>
  20
  21 </para>
  22
  23 <!-- ##### SECTION Stability_Level ##### -->
  24
  25
  26 <!-- ##### MACRO g_new ##### -->
  27 <para>
  28 Allocates @n_structs elements of type @struct_type.
  29 The returned pointer is cast to a pointer to the given type.
  30 If @n_structs is 0 it returns %NULL.
  31 </para>
  32
  33 @struct_type: the type of the elements to allocate.
  34 @n_structs: the number of elements to allocate.
  35 @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
  36
  37
  38 <!-- ##### MACRO g_new0 ##### -->
  39 <para>
  40 Allocates @n_structs elements of type @struct_type, initialized to 0's.
  41 The returned pointer is cast to a pointer to the given type.
  42 If @n_structs is 0 it returns %NULL.
  43 </para>
  44
  45 @struct_type: the type of the elements to allocate.
  46 @n_structs: the number of elements to allocate.
  47 @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
  48
  49
  50 <!-- ##### MACRO g_renew ##### -->
  51 <para>
  52 Reallocates the memory pointed to by @mem, so that it now has space for
  53 @n_structs elements of type @struct_type. It returns the new address of
  54 the memory, which may have been moved.
  55 </para>
  56
  57 @struct_type: the type of the elements to allocate.
  58 @mem: the currently allocated memory.
  59 @n_structs: the number of elements to allocate.
  60 @Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.
  61
  62
  63 <!-- ##### MACRO g_try_new ##### -->
  64 <para>
  65 Attempts to allocate @n_structs elements of type @struct_type, and returns
  66 %NULL on failure. Contrast with g_new(), which aborts the program on failure.
  67 The returned pointer is cast to a pointer to the given type.
  68 If @n_structs is 0 it returns %NULL.
  69 </para>
  70
  71 @struct_type: the type of the elements to allocate.
  72 @n_structs: the number of elements to allocate.
  73 @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
  74 @Since: 2.8
  75
  76
  77 <!-- ##### MACRO g_try_new0 ##### -->
  78 <para>
  79 Attempts to allocate @n_structs elements of type @struct_type, initialized
  80 to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
  81 the program on failure.
  82 The returned pointer is cast to a pointer to the given type.
  83 If @n_counts is 0 it returns %NULL.
  84 </para>
  85
  86 @struct_type: the type of the elements to allocate.
  87 @n_structs: the number of elements to allocate.
  88 @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
  89 @Since: 2.8
  90
  91
  92 <!-- ##### MACRO g_try_renew ##### -->
  93 <para>
  94 Attempts to reallocate the memory pointed to by @mem, so that it now has
  95 space for @n_structs elements of type @struct_type, and returns %NULL on
  96 failure. Contrast with g_renew(), which aborts the program on failure.
  97 It returns the new address of the memory, which may have been moved.
  98 </para>
  99
 100 @struct_type: the type of the elements to allocate.
 101 @mem: the currently allocated memory.
 102 @n_structs: the number of elements to allocate.
 103 @Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.
 104 @Since: 2.8
 105
 106
 107 <!-- ##### FUNCTION g_malloc ##### -->
 108 <para>
 109 Allocates @n_bytes bytes of memory.
 110 If @n_bytes is 0 it returns %NULL.
 111 </para>
 112
 113 @n_bytes: the number of bytes to allocate.
 114 @Returns: a pointer to the allocated memory.
 115
 116
 117 <!-- ##### FUNCTION g_malloc0 ##### -->
 118 <para>
 119 Allocates @n_bytes bytes of memory, initialized to 0's.
 120 If @n_bytes is 0 it returns %NULL.
 121 </para>
 122
 123 @n_bytes: the number of bytes to allocate.
 124 @Returns: a pointer to the allocated memory.
 125
 126
 127 <!-- ##### FUNCTION g_realloc ##### -->
 128 <para>
 129 Reallocates the memory pointed to by @mem, so that it now has space for
 130 @n_bytes bytes of memory. It returns the new address of the memory, which may
 131 have been moved. @mem may be %NULL, in which case it's considered to
 132 have zero-length. @n_bytes may be 0, in which case %NULL will be returned.
 133 </para>
 134
 135 @mem: the memory to reallocate.
 136 @n_bytes: new size of the memory in bytes.
 137 @Returns: the new address of the allocated memory.
 138
 139
 140 <!-- ##### FUNCTION g_try_malloc ##### -->
 141 <para>
 142 Attempts to allocate @n_bytes, and returns %NULL on failure.
 143 Contrast with g_malloc(), which aborts the program on failure.
 144 </para>
 145
 146 @n_bytes: number of bytes to allocate.
 147 @Returns: the allocated memory, or %NULL.
 148
 149
 150 <!-- ##### FUNCTION g_try_malloc0 ##### -->
 151 <para>
 152 Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
 153 failure. Contrast with g_malloc0(), which aborts the program on failure.
 154 </para>
 155
 156 @n_bytes: number of bytes to allocate.
 157 @Returns: the allocated memory, or %NULL.
 158 @Since: 2.8
 159
 160
 161 <!-- ##### FUNCTION g_try_realloc ##### -->
 162 <para>
 163 Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
 164 on failure. Contrast with g_realloc(), which aborts the program
 165 on failure. If @mem is %NULL, behaves the same as g_try_malloc().
 166 </para>
 167
 168 @mem: previously-allocated memory, or %NULL.
 169 @n_bytes: number of bytes to allocate.
 170 @Returns: the allocated memory, or %NULL.
 171
 172
 173 <!-- ##### FUNCTION g_free ##### -->
 174 <para>
 175 Frees the memory pointed to by @mem.
 176 If @mem is %NULL it simply returns.
 177 </para>
 178
 179 @mem: the memory to free.
 180
 181
 182 <!-- ##### MACRO g_alloca ##### -->
 183 <para>
 184 Allocates @size bytes on the stack; these bytes will be freed when the current
 185 stack frame is cleaned up. This macro essentially just wraps the
 186 <function>alloca()</function> function present on most UNIX variants.
 187 Thus it provides the same advantages and pitfalls as <function>alloca()</function>:
 188 <variablelist>
 189   <varlistentry><term></term><listitem><para>
 190     + <function>alloca()</function> is very fast, as on most systems it's implemented by just adjusting
 191     the stack pointer register.
 192   </para></listitem></varlistentry>
 193   <varlistentry><term></term><listitem><para>
 194     + It doesn't cause any memory fragmentation, within its scope, separate <function>alloca()</function>
 195     blocks just build up and are released together at function end.
 196   </para></listitem></varlistentry>
 197   <varlistentry><term></term><listitem><para>
 198     - Allocation sizes have to fit into the current stack frame. For instance in a
 199       threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
 200       so be sparse with <function>alloca()</function> uses.
 201   </para></listitem></varlistentry>
 202   <varlistentry><term></term><listitem><para>
 203     - Allocation failure due to insufficient stack space is not indicated with a %NULL
 204       return like e.g. with <function>malloc()</function>. Instead, most systems probably handle it the same
 205       way as out of stack space situations from infinite function recursion, i.e.
 206       with a segmentation fault.
 207   </para></listitem></varlistentry>
 208   <varlistentry><term></term><listitem><para>
 209     - Special care has to be taken when mixing <function>alloca()</function> with GNU C variable sized arrays.
 210       Stack space allocated with <function>alloca()</function> in the same scope as a variable sized array
 211       will be freed together with the variable sized array upon exit of that scope, and
 212       not upon exit of the enclosing function scope.
 213   </para></listitem></varlistentry>
 214 </variablelist>
 215
 216 </para>
 217
 218 @size:    number of bytes to allocate.
 219 @Returns: space for @size bytes, allocated on the stack
 220
 221
 222 <!-- ##### MACRO g_newa ##### -->
 223 <para>
 224 Wraps g_alloca() in a more typesafe manner.
 225 </para>
 226
 227 @struct_type: Type of memory chunks to be allocated
 228 @n_structs:   Number of chunks to be allocated
 229 @Returns:     Pointer to stack space for @n_structs chunks of type @struct_type
 230
 231
 232 <!-- ##### MACRO g_memmove ##### -->
 233 <para>
 234
 235 </para>
 236
 237 @dest:
 238 @src:
 239 @len:
 240
 241
 242 <!-- ##### FUNCTION g_memdup ##### -->
 243 <para>
 244 Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
 245 from @mem. If @mem is %NULL it returns %NULL.
 246 </para>
 247
 248 @mem: the memory to copy.
 249 @byte_size: the number of bytes to copy.
 250 @Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
 251 is %NULL.
 252
 253
 254 <!-- ##### STRUCT GMemVTable ##### -->
 255 <para>
 256 A set of functions used to perform memory allocation. The same #GMemVTable must
 257 be used for all allocations in the same program; a call to g_mem_set_vtable(),
 258 if it exists, should be prior to any use of GLib.
 259 </para>
 260
 261 @malloc: function to use for allocating memory.
 262 @realloc: function to use for reallocating memory.
 263 @free: function to use to free memory.
 264 @calloc: function to use for allocating zero-filled memory.
 265 @try_malloc: function to use for allocating memory without a default error handler.
 266 @try_realloc: function to use for reallocating memory without a default error handler.
 267
 268 <!-- ##### FUNCTION g_mem_set_vtable ##### -->
 269 <para>
 270 Sets the #GMemVTable to use for memory allocation. You can use this to provide
 271 custom memory allocation routines. <emphasis>This function must be called before using any other GLib functions.</emphasis> The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
 272 functions; GLib can provide default implementations of the others.  The <function>malloc()</function>
 273 and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
 274 error-checking for you. @vtable is copied, so need not persist after this
 275 function has been called.
 276 </para>
 277
 278 @vtable: table of memory allocation routines.
 279
 280
 281 <!-- ##### FUNCTION g_mem_is_system_malloc ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @Returns:
 287
 288
 289 <!-- ##### VARIABLE glib_mem_profiler_table ##### -->
 290 <para>
 291 A #GMemVTable containing profiling variants of the memory
 292 allocation functions. Use them together with g_mem_profile()
 293 in order to get information about the memory allocation pattern
 294 of your program.
 295 </para>
 296
 297
 298 <!-- ##### FUNCTION g_mem_profile ##### -->
 299 <para>
 300 Outputs a summary of memory usage.
 301 </para>
 302 <para>
 303 It outputs the frequency of allocations of different sizes,
 304 the total number of bytes which have been allocated,
 305 the total number of bytes which have been freed,
 306 and the difference between the previous two values, i.e. the number of bytes
 307 still in use.
 308 </para>
 309 <para>
 310 Note that this function will not output anything unless you have
 311 previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
 312 </para>
 313
 314
 315