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