Memory Allocation

Memory Allocation — general memory-handling.

Synopsis


#include <glib.h>


#define     g_new                           (struct_type, n_structs)
#define     g_new0                          (struct_type, n_structs)
#define     g_renew                         (struct_type, mem, n_structs)

gpointer    g_malloc                        (gulong n_bytes);
gpointer    g_malloc0                       (gulong n_bytes);
gpointer    g_realloc                       (gpointer mem,
                                             gulong n_bytes);
gpointer    g_try_malloc                    (gulong n_bytes);
gpointer    g_try_realloc                   (gpointer mem,
                                             gulong n_bytes);

void        g_free                          (gpointer mem);

#define     g_alloca                        (size)
#define     g_newa                          (struct_type, n_structs)

#define     g_memmove                       (d,s,n)
gpointer    g_memdup                        (gconstpointer mem,
                                             guint byte_size);

            GMemVTable;
void        g_mem_set_vtable                (GMemVTable *vtable);
gboolean    g_mem_is_system_malloc          (void);

extern      GMemVTable	*glib_mem_profiler_table;
void        g_mem_profile                   (void);

Description

These functions provide support for allocating and freeing memory.

Note

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.

Details

g_new()

#define     g_new(struct_type, n_structs)

Allocates n_structs elements of type struct_type. The returned pointer is cast to a pointer to the given type. If count is 0 it returns NULL.

`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`.

g_new0()

#define     g_new0(struct_type, n_structs)

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 count is 0 it returns NULL.

`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`.

g_renew()

#define     g_renew(struct_type, mem, n_structs)

Reallocates the memory pointed to by mem, so that it now has space for n_struct elements of type struct_type. It returns the new address of the memory, which may have been moved.

`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`.

g_malloc ()

gpointer    g_malloc                        (gulong n_bytes);

Allocates n_bytes bytes of memory. If n_bytes is 0 it returns NULL.

`n_bytes` :	the number of bytes to allocate.
Returns :	a pointer to the allocated memory.

g_malloc0 ()

gpointer    g_malloc0                       (gulong n_bytes);

Allocates n_bytes bytes of memory, initialized to 0's. If n_bytes is 0 it returns NULL.

`n_bytes` :	the number of bytes to allocate.
Returns :	a pointer to the allocated memory.

g_realloc ()

gpointer    g_realloc                       (gpointer mem,
                                             gulong n_bytes);

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.

`mem` :	the memory to reallocate.
`n_bytes` :	new size of the memory in bytes.
Returns :	the new address of the allocated memory.

g_try_malloc ()

gpointer    g_try_malloc                    (gulong n_bytes);

Attempts to allocate n_bytes, and returns NULL on failure. Contrast with g_malloc(), which aborts the program on failure.

`n_bytes` :	number of bytes to allocate.
Returns :	the allocated memory, or `NULL`.

g_try_realloc ()

gpointer    g_try_realloc                   (gpointer mem,
                                             gulong n_bytes);

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().

`mem` :	previously-allocated memory, or `NULL`.
`n_bytes` :	number of bytes to allocate.
Returns :	the allocated memory, or `NULL`.

g_free ()

void        g_free                          (gpointer mem);

Frees the memory pointed to by mem. If mem is NULL it simply returns.

mem : the memory to free.

g_alloca()

#define     g_alloca(size)

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 alloca() function present on most UNIX variants. Thus it provides the same advantages and pitfalls as alloca():

	+ `alloca()` is very fast, as on most systems it's implemented by just adjusting the stack pointer register.
	+ It doesn't cause any memory fragmentation, within its scope, separate `alloca()` blocks just build up and are released together at function end.
	- 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 `alloca()` uses.
	- Allocation failure due to insufficient stack space is not indicated with a `NULL` return like e.g. with `malloc()`. 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.
	- Special care has to be taken when mixing `alloca()` with GNU C variable sized arrays. Stack space allocated with `alloca()` 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.

`size` :	number of bytes to allocate.
Returns :	space for `size` bytes, allocated on the stack

g_newa()

#define     g_newa(struct_type, n_structs)

Wraps g_alloca() in a more typesafe manner.

`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`

g_memmove()

#define     g_memmove(d,s,n)

Copies a block of memory n bytes long, from s to d. The source and destination areas may overlap.

In order to use this function, you must include string.h yourself, because this macro will typically simply resolve to memmove() and GLib does not include string.h for you.

`d` :	the destination address to copy the bytes to.
`s` :	the source address to copy the bytes from.
`n` :	the number of bytes to copy.

g_memdup ()

gpointer    g_memdup                        (gconstpointer mem,
                                             guint byte_size);

Allocates byte_size bytes of memory, and copies byte_size bytes into it from mem. If mem is NULL it returns NULL.

`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`.

GMemVTable

typedef struct {
  gpointer (*malloc)      (gsize    n_bytes);
  gpointer (*realloc)     (gpointer mem,
			   gsize    n_bytes);
  void     (*free)        (gpointer mem);
  /* optional; set to NULL if not used ! */
  gpointer (*calloc)      (gsize    n_blocks,
			   gsize    n_block_bytes);
  gpointer (*try_malloc)  (gsize    n_bytes);
  gpointer (*try_realloc) (gpointer mem,
			   gsize    n_bytes);
} GMemVTable;

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.

`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.

g_mem_set_vtable ()

void        g_mem_set_vtable                (GMemVTable *vtable);

Sets the GMemVTable to use for memory allocation. You can use this to provide custom memory allocation routines. This function must be called before using any other GLib functions. The vtable only needs to provide malloc(), realloc(), and free() functions; GLib can provide default implementations of the others. The malloc() and realloc() 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.

vtable : table of memory allocation routines.

g_mem_is_system_malloc ()

gboolean    g_mem_is_system_malloc          (void);

Checks whether the allocator used by g_malloc() is the system's malloc implementation. If it returns TRUE memory allocated with malloc() can be used interchangeable with memory allocated using g_malloc(). This function is useful for avoiding an extra copy of allocated memory returned by a non-GLib-based API.

A different allocator can be set using g_mem_set_vtable().

Returns : if TRUE, malloc() and g_malloc() can be mixed.

glib_mem_profiler_table

extern GMemVTable	*glib_mem_profiler_table;

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.

g_mem_profile ()

void        g_mem_profile                   (void);

Outputs a summary of memory usage.

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.

Note that this function will not output anything unless you have previously installed the glib_mem_profiler_table with g_mem_set_vtable().