| <!-- ##### SECTION Title ##### --> |
| Memory Allocation |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| general memory-handling. |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| These functions provide support for allocating and freeing memory. |
| </para> |
| <note> |
| <para> |
| If any call to allocate memory fails, the application is terminated. |
| This also means that there is no need to check if the call succeeded. |
| </para> |
| </note> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### MACRO g_new ##### --> |
| <para> |
| Allocates @n_structs elements of type @struct_type. |
| The returned pointer is cast to a pointer to the given type. |
| If @n_structs is 0 it returns %NULL. |
| </para> |
| <para> |
| Since the returned pointer is already casted to the right type, |
| it is normally unnecessary to cast it explicitly, and doing |
| so might hide memory allocation errors. |
| </para> |
| |
| @struct_type: the type of the elements to allocate. |
| @n_structs: the number of elements to allocate. |
| @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. |
| |
| |
| <!-- ##### MACRO g_new0 ##### --> |
| <para> |
| Allocates @n_structs elements of type @struct_type, initialized to 0's. |
| The returned pointer is cast to a pointer to the given type. |
| If @n_structs is 0 it returns %NULL. |
| </para> |
| <para> |
| Since the returned pointer is already casted to the right type, |
| it is normally unnecessary to cast it explicitly, and doing |
| so might hide memory allocation errors. |
| </para> |
| |
| @struct_type: the type of the elements to allocate. |
| @n_structs: the number of elements to allocate. |
| @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. |
| |
| |
| <!-- ##### MACRO g_renew ##### --> |
| <para> |
| Reallocates the memory pointed to by @mem, so that it now has space for |
| @n_structs elements of type @struct_type. It returns the new address of |
| the memory, which may have been moved. |
| </para> |
| |
| @struct_type: the type of the elements to allocate. |
| @mem: the currently allocated memory. |
| @n_structs: the number of elements to allocate. |
| @Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type. |
| |
| |
| <!-- ##### MACRO g_try_new ##### --> |
| <para> |
| Attempts to allocate @n_structs elements of type @struct_type, and returns |
| %NULL on failure. Contrast with g_new(), which aborts the program on failure. |
| The returned pointer is cast to a pointer to the given type. |
| If @n_structs is 0 it returns %NULL. |
| </para> |
| |
| @struct_type: the type of the elements to allocate. |
| @n_structs: the number of elements to allocate. |
| @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. |
| @Since: 2.8 |
| |
| |
| <!-- ##### MACRO g_try_new0 ##### --> |
| <para> |
| Attempts to allocate @n_structs elements of type @struct_type, initialized |
| to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts |
| the program on failure. |
| The returned pointer is cast to a pointer to the given type. |
| If @n_counts is 0 it returns %NULL. |
| </para> |
| |
| @struct_type: the type of the elements to allocate. |
| @n_structs: the number of elements to allocate. |
| @Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. |
| @Since: 2.8 |
| |
| |
| <!-- ##### MACRO g_try_renew ##### --> |
| <para> |
| Attempts to reallocate the memory pointed to by @mem, so that it now has |
| space for @n_structs elements of type @struct_type, and returns %NULL on |
| failure. Contrast with g_renew(), which aborts the program on failure. |
| It returns the new address of the memory, which may have been moved. |
| </para> |
| |
| @struct_type: the type of the elements to allocate. |
| @mem: the currently allocated memory. |
| @n_structs: the number of elements to allocate. |
| @Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type. |
| @Since: 2.8 |
| |
| |
| <!-- ##### FUNCTION g_malloc ##### --> |
| <para> |
| Allocates @n_bytes bytes of memory. |
| If @n_bytes is 0 it returns %NULL. |
| </para> |
| |
| @n_bytes: the number of bytes to allocate. |
| @Returns: a pointer to the allocated memory. |
| |
| |
| <!-- ##### FUNCTION g_malloc0 ##### --> |
| <para> |
| Allocates @n_bytes bytes of memory, initialized to 0's. |
| If @n_bytes is 0 it returns %NULL. |
| </para> |
| |
| @n_bytes: the number of bytes to allocate. |
| @Returns: a pointer to the allocated memory. |
| |
| |
| <!-- ##### FUNCTION g_realloc ##### --> |
| <para> |
| Reallocates the memory pointed to by @mem, so that it now has space for |
| @n_bytes bytes of memory. It returns the new address of the memory, which may |
| have been moved. @mem may be %NULL, in which case it's considered to |
| have zero-length. @n_bytes may be 0, in which case %NULL will be returned. |
| </para> |
| |
| @mem: the memory to reallocate. |
| @n_bytes: new size of the memory in bytes. |
| @Returns: the new address of the allocated memory. |
| |
| |
| <!-- ##### FUNCTION g_try_malloc ##### --> |
| <para> |
| Attempts to allocate @n_bytes, and returns %NULL on failure. |
| Contrast with g_malloc(), which aborts the program on failure. |
| </para> |
| |
| @n_bytes: number of bytes to allocate. |
| @Returns: the allocated memory, or %NULL. |
| |
| |
| <!-- ##### FUNCTION g_try_malloc0 ##### --> |
| <para> |
| Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on |
| failure. Contrast with g_malloc0(), which aborts the program on failure. |
| </para> |
| |
| @n_bytes: number of bytes to allocate. |
| @Returns: the allocated memory, or %NULL. |
| @Since: 2.8 |
| |
| |
| <!-- ##### FUNCTION g_try_realloc ##### --> |
| <para> |
| Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL |
| on failure. Contrast with g_realloc(), which aborts the program |
| on failure. If @mem is %NULL, behaves the same as g_try_malloc(). |
| </para> |
| |
| @mem: previously-allocated memory, or %NULL. |
| @n_bytes: number of bytes to allocate. |
| @Returns: the allocated memory, or %NULL. |
| |
| |
| <!-- ##### FUNCTION g_free ##### --> |
| <para> |
| Frees the memory pointed to by @mem. |
| If @mem is %NULL it simply returns. |
| </para> |
| |
| @mem: the memory to free. |
| |
| |
| <!-- ##### VARIABLE g_mem_gc_friendly ##### --> |
| <para> |
| This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable |
| includes the key <link linkend="G_DEBUG">gc-friendly</link>. |
| </para> |
| |
| @Since: 2.10 |
| |
| <!-- ##### MACRO g_alloca ##### --> |
| <para> |
| Allocates @size bytes on the stack; these bytes will be freed when the current |
| stack frame is cleaned up. This macro essentially just wraps the |
| <function>alloca()</function> function present on most UNIX variants. |
| Thus it provides the same advantages and pitfalls as <function>alloca()</function>: |
| <variablelist> |
| <varlistentry><term></term><listitem><para> |
| + <function>alloca()</function> is very fast, as on most systems it's implemented by just adjusting |
| the stack pointer register. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| + It doesn't cause any memory fragmentation, within its scope, separate <function>alloca()</function> |
| blocks just build up and are released together at function end. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| - Allocation sizes have to fit into the current stack frame. For instance in a |
| threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, |
| so be sparse with <function>alloca()</function> uses. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| - Allocation failure due to insufficient stack space is not indicated with a %NULL |
| return like e.g. with <function>malloc()</function>. Instead, most systems probably handle it the same |
| way as out of stack space situations from infinite function recursion, i.e. |
| with a segmentation fault. |
| </para></listitem></varlistentry> |
| <varlistentry><term></term><listitem><para> |
| - Special care has to be taken when mixing <function>alloca()</function> with GNU C variable sized arrays. |
| Stack space allocated with <function>alloca()</function> in the same scope as a variable sized array |
| will be freed together with the variable sized array upon exit of that scope, and |
| not upon exit of the enclosing function scope. |
| </para></listitem></varlistentry> |
| </variablelist> |
| |
| </para> |
| |
| @size: number of bytes to allocate. |
| @Returns: space for @size bytes, allocated on the stack |
| |
| |
| <!-- ##### MACRO g_newa ##### --> |
| <para> |
| Wraps g_alloca() in a more typesafe manner. |
| </para> |
| |
| @struct_type: Type of memory chunks to be allocated |
| @n_structs: Number of chunks to be allocated |
| @Returns: Pointer to stack space for @n_structs chunks of type @struct_type |
| |
| |
| <!-- ##### MACRO g_memmove ##### --> |
| <para> |
| |
| </para> |
| |
| @dest: |
| @src: |
| @len: |
| |
| |
| <!-- ##### FUNCTION g_memdup ##### --> |
| <para> |
| Allocates @byte_size bytes of memory, and copies @byte_size bytes into it |
| from @mem. If @mem is %NULL it returns %NULL. |
| </para> |
| |
| @mem: the memory to copy. |
| @byte_size: the number of bytes to copy. |
| @Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem |
| is %NULL. |
| |
| |
| <!-- ##### STRUCT GMemVTable ##### --> |
| <para> |
| A set of functions used to perform memory allocation. The same #GMemVTable must |
| be used for all allocations in the same program; a call to g_mem_set_vtable(), |
| if it exists, should be prior to any use of GLib. |
| </para> |
| |
| @malloc: function to use for allocating memory. |
| @realloc: function to use for reallocating memory. |
| @free: function to use to free memory. |
| @calloc: function to use for allocating zero-filled memory. |
| @try_malloc: function to use for allocating memory without a default error handler. |
| @try_realloc: function to use for reallocating memory without a default error handler. |
| |
| <!-- ##### FUNCTION g_mem_set_vtable ##### --> |
| <para> |
| Sets the #GMemVTable to use for memory allocation. You can use this to provide |
| 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> |
| functions; GLib can provide default implementations of the others. The <function>malloc()</function> |
| and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle |
| error-checking for you. @vtable is copied, so need not persist after this |
| function has been called. |
| </para> |
| |
| @vtable: table of memory allocation routines. |
| |
| |
| <!-- ##### FUNCTION g_mem_is_system_malloc ##### --> |
| <para> |
| |
| </para> |
| |
| @Returns: |
| |
| |
| <!-- ##### VARIABLE glib_mem_profiler_table ##### --> |
| <para> |
| A #GMemVTable containing profiling variants of the memory |
| allocation functions. Use them together with g_mem_profile() |
| in order to get information about the memory allocation pattern |
| of your program. |
| </para> |
| |
| |
| <!-- ##### FUNCTION g_mem_profile ##### --> |
| <para> |
| Outputs a summary of memory usage. |
| </para> |
| <para> |
| It outputs the frequency of allocations of different sizes, |
| the total number of bytes which have been allocated, |
| the total number of bytes which have been freed, |
| and the difference between the previous two values, i.e. the number of bytes |
| still in use. |
| </para> |
| <para> |
| Note that this function will not output anything unless you have |
| previously installed the #glib_mem_profiler_table with g_mem_set_vtable(). |
| </para> |
| |
| |
| |