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