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