Memory Allocation

Name

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_memmove                       (d,s,n)
gpointer    g_memdup                        (gconstpointer mem,
                                             guint byte_size);

struct      GMemVTable;
void        g_mem_set_vtable                (GMemVTable *vtable);

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 count elements of type type. The returned pointer is cast to a pointer to the given type. If count is 0 it returns NULL.

struct_type : 
n_structs : 
Returns :a pointer to the allocated memory, cast to a pointer to type.


g_new0()

#define     g_new0(struct_type, n_structs)

Allocates count elements of type 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 : 
n_structs : 
Returns :a pointer to the allocated memory, cast to a pointer to 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 count elements of type type. It returns the new address of the memory, which may have been moved.

struct_type : 
mem :the currently allocated memory.
n_structs : 
Returns :a pointer to the new allocated memory, cast to a pointer to type.


g_malloc ()

gpointer    g_malloc                        (gulong n_bytes);

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

n_bytes : 
Returns :a pointer to the allocated memory.


g_malloc0 ()

gpointer    g_malloc0                       (gulong n_bytes);

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

n_bytes : 
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 size 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.

size :number of bytes to allocate


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.


struct GMemVTable

struct GMemVTable
{
  gpointer (*malloc)      (gsize    n_bytes);
  gpointer (*realloc)     (gpointer mem,
			   gsize    n_bytes);
  void     (*free)        (gpointer mem);
  /* optional */
  gpointer (*calloc)      (gsize    n_blocks,
			   gsize    n_block_bytes);
  gpointer (*try_malloc)  (gsize    n_bytes);
  gpointer (*try_realloc) (gpointer mem,
			   gsize    n_bytes);
};

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.

gpointer (*malloc) (gsize n_bytes)function to use for allocating memory
gpointer (*realloc) (gpointer mem, gsize n_bytes)function to use for reallocating memory
void (*free) (gpointer mem)function to use to free memory
gpointer (*calloc) (gsize n_blocks, gsize n_block_bytes)function to use for allocating zero-filled memory
gpointer (*try_malloc) (gsize n_bytes)function to use for allocating memory without a default error handler
gpointer (*try_realloc) (gpointer mem, gsize n_bytes)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.


glib_mem_profiler_table

extern GMemVTable	*glib_mem_profiler_table;


g_mem_profile ()

void        g_mem_profile                   (void);

Outputs a summary of memory usage. To use this function you must configure glib with the flag '--enable-mem-profile=yes' before compiling.

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.