Common Allocation Routines
[Common]

Classes
struct	Gan_MemoryStack
	Structure to hold state of stack memory blocks. More...
Defines
#define	obj_type   int x
#define	TM_TEST_MAGIC   1
#define	TM_MAGIC_NUMBER   0x2f3ee7b1
Typedefs
typedef void(*	Gan_FreeFunc )(void *)
	Generic free function type.
typedef void *(*	Gan_CopyFunc )(void *)
	Generic copy function type.
typedef double	Gan_BigType
	Big C type for byte alignment.
typedef Gan_MemoryStack	Gan_MemoryStack
	Structure to hold state of stack memory blocks.
Functions
void	gan_free_va (void *ptr,...)
	Frees a NULL terminated variable argument list of memory blocks.
void *	gan_malloc_object (TYPE obj_type)
	Macro: Allocate an object of a specific type using malloc().
void *	gan_malloc_array (TYPE obj_type, unsigned size)
	Macro: Allocate an array of objects of a specific type using malloc().
void *	gan_realloc_array (TYPE obj_type, void *ptr, unsigned size)
	Macro: Reallocate an array of objects using realloc().
Gan_MemoryStack *	gan_memory_stack_form (Gan_MemoryStack *ms, int nblocks, size_t bsize)
	Initialise temporary memory allocation structure.
void *	gan_ms_malloc (Gan_MemoryStack *ms, size_t size)
	Temporary memory allocation routine, faster than malloc().
void	gan_ms_free (Gan_MemoryStack *ms, void *ptr)
	Temporary memory free routine.
void	gan_ms_free_va (Gan_MemoryStack *ms, void *ptr,...)
	Frees a list of temporaray blocks terminated by NULL.
void	gan_memory_stack_free (Gan_MemoryStack *ms)
	Frees all temporary memory.
void	gan_memory_stack_clean (Gan_MemoryStack *ms)
	Frees unused temporary memory.
size_t	gan_memory_stack_total (Gan_MemoryStack *ms)
	Returns the total temporary memory currently allocated.
Gan_MemoryStack *	gan_memory_stack_alloc (int nblocks, size_t bsize)
	Macro: Allocate and initialise temporary memory allocation structure.
void *	gan_ms_malloc_object (Gan_MemoryStack *ms, TYPE obj_type)
	Macro: Dynamically allocate one item of a specific type with "stack" memory.
void *	gan_ms_malloc_array (Gan_MemoryStack *ms, TYPE obj_type, size_t size)
	Macro: Dynamically allocate n items of a specific type with "stack" memory.

---

Function Documentation

void gan_free_va (  void *  ptr,   ... )

Frees a NULL terminated variable argument list of memory blocks. Parameters: ptr  The first memory block to free ...  List of other blocks to free, terminated by NULL Returns: No value. Invokes free() to free each memory block in the list of pointers starting with ptr and ending with NULL . See also: gan_malloc_object(), gan_malloc_array().

void* gan_malloc_array (  TYPE  obj_type, unsigned  size )

Macro: Allocate an array of objects of a specific type using malloc(). Parameters: obj_type  The type of objects to be allocated size  The number of objects to allocate for in the array Returns: The allocated array of objects, or NULL on failure. Invokes malloc() to dynamically allocate an array of objects of a specific type. See also: gan_malloc_object(), gan_realloc_array().

void* gan_malloc_object (  TYPE  obj_type  )

Macro: Allocate an object of a specific type using malloc(). Parameters: obj_type  The type of object to be allocated Returns: Pointer to the allocated object, or NULL on failure. Invokes malloc() to dynamically allocate an object of a specific type. See also: gan_malloc_array().

Gan_MemoryStack* gan_memory_stack_alloc (  int  nblocks, size_t  bsize )

Macro: Allocate and initialise temporary memory allocation structure. Parameters: nblocks  Maximum number of blocks of memory to allow bsize  Size of each block in bytes Returns: Pointer to new structure, or NULL on failure.

void gan_memory_stack_clean (  Gan_MemoryStack *  ms  )

Frees unused temporary memory. Parameters: ms  Pointer to memory stack structure Frees memory stack down to the last gan_ms_free() call.

Gan_MemoryStack * gan_memory_stack_form (  Gan_MemoryStack *  ms, int  nblocks, size_t  bsize )

Initialise temporary memory allocation structure. Parameters: ms  Memoru stack structure pointer nblocks  Maximum number of blocks of memory to allow bsize  Size of each block in bytes Returns: Pointer to initialised structure, or NULL on failure.

void gan_memory_stack_free (  Gan_MemoryStack *  ms  )

Frees all temporary memory. Parameters: ms  Pointer to memory stack structure Frees all memory allocated using calls to gan_ms_malloc().

size_t gan_memory_stack_total (  Gan_MemoryStack *  ms  )

Returns the total temporary memory currently allocated. Parameters: ms  Pointer to memory stack structure Returns the total temporary memory currently allocated by calls to gan_ms_malloc().

void gan_ms_free (  Gan_MemoryStack *  ms, void *  ptr )

Temporary memory free routine. Parameters: ms  Pointer to memory stack structure ptr  Pointer to memory area to free, as returned by gan_ms_malloc() Temporary memory free routine, Memory must be freed in reverse of the order it was allocated using gan_ms_malloc(). gan_ms_free() does not actually free any memory, but allows the marked memory to be used in subsequent gan_ms_malloc() calls. After using the temporary memory, call gan_memory_stack_free() to actually free the memory blocks.

void gan_ms_free_va (  Gan_MemoryStack *  ms, void *  ptr,   ... )

Frees a list of temporaray blocks terminated by NULL. Parameters: ms  Pointer to memory stack structure ptr  The first memory block to free ...  List of other blocks to free, terminated by NULL Frees a list of temporaray blocks allocated by gan_ms_malloc(), teminated by NULL. gan_ms_free() is called for each block, preserving the order of the arguments in the calls.

void * gan_ms_malloc (  Gan_MemoryStack *  ms, size_t  size )

Temporary memory allocation routine, faster than malloc(). Parameters: ms  Pointer to memory stack structure size  Amount of memory to allocate in bytes Returns: Non NULL successfully allocated block, NULL on failure For allocating chunks of memory which can be freed in reverse order, The module allocates large blocks at a time using malloc(), the blocks being "a lot" bigger than the chunks to be gan_ms_malloc()'d, to avoid wasting memory. Calls to gan_ms_malloc() then fill up the current block, and when the end is reached another block is malloc()'d. There's a dirty bit concerning memory alignment where I assume that everything should be aligned according to a "big" type (double). malloc() guarantees that it returns pointers that may be safely cast to any pointer type, but I (PFM) don't know how to do that properly in C.

void* gan_ms_malloc_array (  Gan_MemoryStack *  ms, TYPE  obj_type, size_t  size )

Macro: Dynamically allocate n items of a specific type with "stack" memory. Parameters: ms  Memory stack structure obj_type  The type of objects to be allocated size  The number of objects to allocate for in the array Returns: The allocated array of objects, or NULL on failure. Allocation function for allocating size items of the given obj_type in temporary stack-style memory. Implemented as a macro call to gan_ms_malloc(). See also: gan_ms_malloc_object(), gan_ms_malloc().

void* gan_ms_malloc_object (  Gan_MemoryStack *  ms, TYPE  obj_type )

Macro: Dynamically allocate one item of a specific type with "stack" memory. Parameters: ms  Memory stack structure obj_type  The type of objects to be allocated Returns: The allocated object, or NULL on failure. Allocation function for allocating 1 item of the given obj_type in temporary stack-style memory. Implemented as a macro call to gan_ms_malloc(). See also: gan_ms_malloc().

void* gan_realloc_array (  TYPE  obj_type, void *  ptr, unsigned  size )

Macro: Reallocate an array of objects using realloc(). Parameters: obj_type  The type of objects to be allocated ptr  The existing array to be reallocated or NULL size  The number of objects to allocate for in the array Returns: The reallocated array of objects, or NULL on failure. Invokes realloc() to dynamically reallocate an array of objects of a specific type. If ptr is passed as NULL then it is equivalent to calling gan_malloc_array(). See also: gan_malloc_array().

---