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
  12 <note>
  13 <para>
  14 If any call to allocate memory fails, the application is terminated.
  15 This also means that there is no need to check if the call succeeded.
  16 </para>
  17 </note>
  18
  19 <note>
  20 <para>
  21 It's important to match g_malloc() with g_free(), plain malloc() with free(),
  22 and (if you're using C++) new with delete and new[] with delete[]. Otherwise
  23 bad things can happen, since these allocators may use different memory
  24 pools (and new/delete call constructors and destructors). See also
  25 g_mem_set_vtable().
  26 </para>
  27 </note>
  28
  29 <!-- ##### SECTION See_Also ##### -->
  30 <para>
  31
  32 </para>
  33
  34 <!-- ##### SECTION Stability_Level ##### -->
  35
  36
  37 <!-- ##### MACRO g_new ##### -->
  38 <para>
  39 Allocates @n_structs elements of type @struct_type.
  40 The returned pointer is cast to a pointer to the given type.
  41 If @n_structs is 0 it returns %NULL.
  42 Care is taken to avoid overflow when calculating the size of the allocated block.
  43 </para>
  44 <para>
  45 Since the returned pointer is already casted to the right type,
  46 it is normally unnecessary to cast it explicitly, and doing
  47 so might hide memory allocation errors.
  48 </para>
  49
  50 @struct_type: the type of the elements to allocate
  51 @n_structs: the number of elements to allocate
  52 @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
  53
  54
  55 <!-- ##### MACRO g_new0 ##### -->
  56 <para>
  57 Allocates @n_structs elements of type @struct_type, initialized to 0's.
  58 The returned pointer is cast to a pointer to the given type.
  59 If @n_structs is 0 it returns %NULL.
  60 Care is taken to avoid overflow when calculating the size of the allocated block.
  61 </para>
  62 <para>
  63 Since the returned pointer is already casted to the right type,
  64 it is normally unnecessary to cast it explicitly, and doing
  65 so might hide memory allocation errors.
  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
  72
  73 <!-- ##### MACRO g_renew ##### -->
  74 <para>
  75 Reallocates the memory pointed to by @mem, so that it now has space for
  76 @n_structs elements of type @struct_type. It returns the new address of
  77 the memory, which may have been moved.
  78 Care is taken to avoid overflow when calculating the size of the allocated block.
  79 </para>
  80
  81 @struct_type: the type of the elements to allocate
  82 @mem: the currently allocated memory
  83 @n_structs: the number of elements to allocate
  84 @Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
  85
  86
  87 <!-- ##### MACRO g_try_new ##### -->
  88 <para>
  89 Attempts to allocate @n_structs elements of type @struct_type, and returns
  90 %NULL on failure. Contrast with g_new(), which aborts the program on failure.
  91 The returned pointer is cast to a pointer to the given type.
  92 The function returns %NULL when @n_structs is 0 of if an overflow occurs.
  93 </para>
  94
  95 @struct_type: the type of the elements to allocate
  96 @n_structs: the number of elements to allocate
  97 @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
  98 @Since: 2.8
  99
 100
 101 <!-- ##### MACRO g_try_new0 ##### -->
 102 <para>
 103 Attempts to allocate @n_structs elements of type @struct_type, initialized
 104 to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
 105 the program on failure.
 106 The returned pointer is cast to a pointer to the given type.
 107 The function returns %NULL when @n_structs is 0 of if an overflow occurs.
 108 </para>
 109
 110 @struct_type: the type of the elements to allocate
 111 @n_structs: the number of elements to allocate
 112 @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
 113 @Since: 2.8
 114
 115
 116 <!-- ##### MACRO g_try_renew ##### -->
 117 <para>
 118 Attempts to reallocate the memory pointed to by @mem, so that it now has
 119 space for @n_structs elements of type @struct_type, and returns %NULL on
 120 failure. Contrast with g_renew(), which aborts the program on failure.
 121 It returns the new address of the memory, which may have been moved.
 122 The function returns %NULL if an overflow occurs.
 123 </para>
 124
 125 @struct_type: the type of the elements to allocate
 126 @mem: the currently allocated memory
 127 @n_structs: the number of elements to allocate
 128 @Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
 129 @Since: 2.8
 130
 131
 132 <!-- ##### FUNCTION g_malloc ##### -->
 133 <para>
 134 Allocates @n_bytes bytes of memory.
 135 If @n_bytes is 0 it returns %NULL.
 136 </para>
 137
 138 @n_bytes: the number of bytes to allocate
 139 @Returns: a pointer to the allocated memory
 140
 141
 142 <!-- ##### FUNCTION g_malloc0 ##### -->
 143 <para>
 144 Allocates @n_bytes bytes of memory, initialized to 0's.
 145 If @n_bytes is 0 it returns %NULL.
 146 </para>
 147
 148 @n_bytes: the number of bytes to allocate
 149 @Returns: a pointer to the allocated memory
 150
 151
 152 <!-- ##### FUNCTION g_realloc ##### -->
 153 <para>
 154 Reallocates the memory pointed to by @mem, so that it now has space for
 155 @n_bytes bytes of memory. It returns the new address of the memory, which may
 156 have been moved. @mem may be %NULL, in which case it's considered to
 157 have zero-length. @n_bytes may be 0, in which case %NULL will be returned
 158 and @mem will be freed unless it is %NULL.
 159 </para>
 160
 161 @mem: the memory to reallocate
 162 @n_bytes: new size of the memory in bytes
 163 @Returns: the new address of the allocated memory
 164
 165
 166 <!-- ##### FUNCTION g_try_malloc ##### -->
 167 <para>
 168 Attempts to allocate @n_bytes, and returns %NULL on failure.
 169 Contrast with g_malloc(), which aborts the program on failure.
 170 </para>
 171
 172 @n_bytes: number of bytes to allocate.
 173 @Returns: the allocated memory, or %NULL.
 174
 175
 176 <!-- ##### FUNCTION g_try_malloc0 ##### -->
 177 <para>
 178 Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
 179 failure. Contrast with g_malloc0(), which aborts the program on failure.
 180 </para>
 181
 182 @n_bytes: number of bytes to allocate
 183 @Returns: the allocated memory, or %NULL
 184 @Since: 2.8
 185
 186
 187 <!-- ##### FUNCTION g_try_realloc ##### -->
 188 <para>
 189 Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
 190 on failure. Contrast with g_realloc(), which aborts the program
 191 on failure. If @mem is %NULL, behaves the same as g_try_malloc().
 192 </para>
 193
 194 @mem: previously-allocated memory, or %NULL.
 195 @n_bytes: number of bytes to allocate.
 196 @Returns: the allocated memory, or %NULL.
 197
 198
 199 <!-- ##### FUNCTION g_malloc_n ##### -->
 200 <para>
 201 This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
 202 but care is taken to detect possible overflow during multiplication.
 203 </para>
 204
 205 @n_blocks: the number of blocks to allocate
 206 @n_block_bytes: the size of each block in bytes
 207 @Returns: a pointer to the allocated memory
 208 @Since: 2.24
 209
 210
 211 <!-- ##### FUNCTION g_malloc0_n ##### -->
 212 <para>
 213 This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
 214 but care is taken to detect possible overflow during multiplication.
 215 </para>
 216
 217 @n_blocks: the number of blocks to allocate
 218 @n_block_bytes: the size of each block in bytes
 219 @Returns: a pointer to the allocated memory
 220 @Since: 2.24
 221
 222
 223 <!-- ##### FUNCTION g_realloc_n ##### -->
 224 <para>
 225 This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
 226 but care is taken to detect possible overflow during multiplication.
 227 </para>
 228
 229 @mem: the memory to reallocate
 230 @n_blocks: the number of blocks to allocate
 231 @n_block_bytes: the size of each block in bytes
 232 @Returns: the new address of the allocated memory
 233 @Since: 2.24
 234
 235
 236 <!-- ##### FUNCTION g_try_malloc_n ##### -->
 237 <para>
 238 This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
 239 but care is taken to detect possible overflow during multiplication.
 240 </para>
 241
 242 @n_blocks: the number of blocks to allocate
 243 @n_block_bytes: the size of each block in bytes
 244 @Returns: the allocated memory, or %NULL.
 245 @Since: 2.24
 246
 247
 248 <!-- ##### FUNCTION g_try_malloc0_n ##### -->
 249 <para>
 250 This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
 251 but care is taken to detect possible overflow during multiplication.
 252 </para>
 253
 254 @n_blocks: the number of blocks to allocate
 255 @n_block_bytes: the size of each block in bytes
 256 @Returns: the allocated memory, or %NULL
 257 @Since: 2.24
 258
 259
 260 <!-- ##### FUNCTION g_try_realloc_n ##### -->
 261 <para>
 262 This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
 263 but care is taken to detect possible overflow during multiplication.
 264 </para>
 265
 266 @mem: previously-allocated memory, or %NULL.
 267 @n_blocks: the number of blocks to allocate
 268 @n_block_bytes: the size of each block in bytes
 269 @Returns: the allocated memory, or %NULL.
 270 @Since: 2.24
 271
 272
 273 <!-- ##### FUNCTION g_free ##### -->
 274 <para>
 275 Frees the memory pointed to by @mem.
 276 If @mem is %NULL it simply returns.
 277 </para>
 278
 279 @mem: the memory to free
 280
 281
 282 <!-- ##### VARIABLE g_mem_gc_friendly ##### -->
 283 <para>
 284 This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
 285 includes the key <link linkend="G_DEBUG">gc-friendly</link>.
 286 </para>
 287
 288
 289 <!-- ##### MACRO g_alloca ##### -->
 290 <para>
 291 Allocates @size bytes on the stack; these bytes will be freed when the current
 292 stack frame is cleaned up. This macro essentially just wraps the alloca()
 293 function present on most UNIX variants.
 294 Thus it provides the same advantages and pitfalls as alloca():
 295 <variablelist>
 296   <varlistentry><term></term><listitem><para>
 297     + alloca() is very fast, as on most systems it's implemented by just adjusting
 298     the stack pointer register.
 299   </para></listitem></varlistentry>
 300   <varlistentry><term></term><listitem><para>
 301     + It doesn't cause any memory fragmentation, within its scope, separate alloca()
 302     blocks just build up and are released together at function end.
 303   </para></listitem></varlistentry>
 304   <varlistentry><term></term><listitem><para>
 305     - Allocation sizes have to fit into the current stack frame. For instance in a
 306       threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
 307       so be sparse with alloca() uses.
 308   </para></listitem></varlistentry>
 309   <varlistentry><term></term><listitem><para>
 310     - Allocation failure due to insufficient stack space is not indicated with a %NULL
 311       return like e.g. with malloc(). Instead, most systems probably handle it the same
 312       way as out of stack space situations from infinite function recursion, i.e.
 313       with a segmentation fault.
 314   </para></listitem></varlistentry>
 315   <varlistentry><term></term><listitem><para>
 316     - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
 317       Stack space allocated with alloca() in the same scope as a variable sized array
 318       will be freed together with the variable sized array upon exit of that scope, and
 319       not upon exit of the enclosing function scope.
 320   </para></listitem></varlistentry>
 321 </variablelist>
 322
 323 </para>
 324
 325 @size:    number of bytes to allocate.
 326 @Returns: space for @size bytes, allocated on the stack
 327
 328
 329 <!-- ##### MACRO g_newa ##### -->
 330 <para>
 331 Wraps g_alloca() in a more typesafe manner.
 332 </para>
 333
 334 @struct_type: Type of memory chunks to be allocated
 335 @n_structs:   Number of chunks to be allocated
 336 @Returns:     Pointer to stack space for @n_structs chunks of type @struct_type
 337
 338
 339 <!-- ##### MACRO g_memmove ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @dest:
 345 @src:
 346 @len:
 347
 348
 349 <!-- ##### FUNCTION g_memdup ##### -->
 350 <para>
 351 Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
 352 from @mem. If @mem is %NULL it returns %NULL.
 353 </para>
 354
 355 @mem: the memory to copy.
 356 @byte_size: the number of bytes to copy.
 357 @Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
 358 is %NULL.
 359
 360
 361 <!-- ##### STRUCT GMemVTable ##### -->
 362 <para>
 363 A set of functions used to perform memory allocation. The same #GMemVTable must
 364 be used for all allocations in the same program; a call to g_mem_set_vtable(),
 365 if it exists, should be prior to any use of GLib.
 366 </para>
 367
 368 @malloc: function to use for allocating memory.
 369 @realloc: function to use for reallocating memory.
 370 @free: function to use to free memory.
 371 @calloc: function to use for allocating zero-filled memory.
 372 @try_malloc: function to use for allocating memory without a default error handler.
 373 @try_realloc: function to use for reallocating memory without a default error handler.
 374
 375 <!-- ##### FUNCTION g_mem_set_vtable ##### -->
 376 <para>
 377 Sets the #GMemVTable to use for memory allocation. You can use this to provide
 378 custom memory allocation routines. <emphasis>This function must be called
 379 before using any other GLib functions.</emphasis> The @vtable only needs to
 380 provide malloc(), realloc(), and free() functions; GLib can provide default
 381 implementations of the others. The malloc() and realloc() implementations
 382 should return %NULL on failure, GLib will handle error-checking for you.
 383 @vtable is copied, so need not persist after this function has been called.
 384 </para>
 385
 386 @vtable: table of memory allocation routines.
 387
 388
 389 <!-- ##### FUNCTION g_mem_is_system_malloc ##### -->
 390 <para>
 391
 392 </para>
 393
 394 @Returns:
 395
 396
 397 <!-- ##### VARIABLE glib_mem_profiler_table ##### -->
 398 <para>
 399 A #GMemVTable containing profiling variants of the memory
 400 allocation functions. Use them together with g_mem_profile()
 401 in order to get information about the memory allocation pattern
 402 of your program.
 403 </para>
 404
 405
 406 <!-- ##### FUNCTION g_mem_profile ##### -->
 407 <para>
 408 Outputs a summary of memory usage.
 409 </para>
 410 <para>
 411 It outputs the frequency of allocations of different sizes,
 412 the total number of bytes which have been allocated,
 413 the total number of bytes which have been freed,
 414 and the difference between the previous two values, i.e. the number of bytes
 415 still in use.
 416 </para>
 417 <para>
 418 Note that this function will not output anything unless you have
 419 previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
 420 </para>
 421
 422
 423