MEMORY

Memory Allocation/Freeing. More...

Data Structures
struct	T_memBlockHeader_tag

Macros
#define	MEM_BLOCK_TAG_SIZE   4

Typedefs
typedef struct T_memBlockHeader_tag	T_memBlockHeader

Functions
T_word32	FreeMemory (T_void)
T_void *	MemAlloc (T_word32 size)
T_void	MemCheck (T_word16 num)
T_void	MemCheckData (T_void *p_data)
T_void	MemDumpDiscarded (T_void)
T_void	MemFlushDiscardable (T_void)
T_void	MemFree (T_void *p_data)
T_word32	MemGetAllocated (T_void)
T_word32	MemGetMaxAllocated (T_void)
T_void	MemMarkDiscardable (T_void *p_data, T_memDiscardCallbackFunc p_callback)
T_void	MemReclaimDiscardable (T_void *p_data)

Detailed Description

Memory Allocation/Freeing.

The Memory allocation system is here. There is a fair amount of specialized code going on here as we allocate and free memory. When debug mode is enabled, memory can be tracked by who allocated it and if there are any memory leaks.

See Also

http://www.amuletsandarmor.com/AALicense.txt

Macro Definition Documentation

#define MEM_BLOCK_TAG_SIZE   4

Typedef Documentation

typedef struct T_memBlockHeader_tag T_memBlockHeader

Function Documentation

T_word32 FreeMemory

(

T_void

)

T_void* MemAlloc

(

T_word32

size)

Currently, this routine is provided more for debugging than an actual utility. However, this should be the one routine that everyone calls to allocate memory (no matter what system). Since we use this for debugging, we will assign a number to each piece of memory that is allocated and will attach a "tag" at the beginning to make the system have a way to check if we are later freeing a block, or just random memory. Space is also provided to allow the block to be declared as discard- able. A discardable block needs to be able to be placed on a double link list and have a call back function (for when the block is actually discarded). See MemMarkDiscardable for more details.

NOTE: I'm sure what the size limitations for this will be, so we had best stick to 64K or smaller allocations. Note that this routine is also made for blocks of typically larger than 256 bytes. If you got alot of small parts, you might want to try doing it a different way.

Parameters

size	– Amount of memory to allocate

Returns

Pointer or NULL to memory block.

T_void MemCheck

(

T_word16

num)

T_void MemCheckData

(

T_void *

p_data)

T_void MemDumpDiscarded

(

T_void

)

MemDumpDiscarded is for debugging purposes only (and only will be compiled in debug mode). It will output a list of blocks to the file "debugmem.txt".

NOTE: None really.

T_void MemFlushDiscardable

(

T_void

)

MemFlushDiscardable goes through the list of discardable memory and frees it out. This is useful for checking memory leaks or just wanting the system to reset to the beginning.

NOTE: None really.

T_void MemFree

(

T_void *

p_data)

MemFree frees a block of memory that was previously allocated. It also checks the integrity of the pointer given to it. If the pointer is NULL, it crashes. If the pointer does not point to a block that was allocated, it crashes.

NOTE: None that I can think of (except this will definitely slow down the system a little).

Parameters

p_data

– Pointer to block to free Normally we can assume p_data points to data and is not NULL.

T_word32 MemGetAllocated

(

T_void

)

MemGetAllocated returns the total amount of memory allocated.

NOTE: None really.

Returns

Number bytes allocated

T_word32 MemGetMaxAllocated

(

T_void

)

MemGetMaxAllocated returns the maximum amount of memory that has been allocated at any one time.

NOTE: None really.

Returns

Max bytes allocated since program started.

T_void MemMarkDiscardable	(	T_void *	p_data,
		T_memDiscardCallbackFunc	p_callback
	)

As an alternative to freeing a block of memory, you may choose to make the memory discardable. Doing so allows you to keep the block in memory as long as possible without automatically get rid of it. This allows for other routines to keep blocks cached in memory instead of accessing the disk drive over and over again. To facilitate discardable blocks, a callback routine is also passed to tell the original caller that the block is no longer in memory. Typically the callback routine will remove the item from a list.

NOTE: All routines that use memory have to use MemAlloc/MemFree or else several discarded blocks may be using up all the standard memory. Only MemAlloc actually calls the routines to free up discarded memory.

Parameters

p_data	– Pointer to the data block
p_callback	– Pointer to the function that should be called when this block is freed from memory. You can use NULL if you don't care, but if you do, you might as well use MemFree since this is the link that allows you to know what the block status really is.

T_void MemReclaimDiscardable

(

T_void *

p_data)

Should you need to use a block that you know you had allocated in in the past and later marked discardable, you can reclaim the block. By calling this routine, you remove the block from the discard list and make it act like a normal block.

NOTE: The caller must keep up with what blocks are discarded and what their original pointers are. The callback function provided in MemMarkDisc() provides a method to note when the block is finally removed.

Parameters

p_data

– Pointer to originally discarded block