geRam

Source file: …\genesis3d\OpenSource\Source\Support\RAM.h

Contents:

Functions: AddAllocation, Allocate, AllocateClear, EnableCriticalCallback, Free_, Realloc, ReportAllocations, SetCriticalCallback

Macro: GE_RAM_ALLOCATE_ARRAY, GE_RAM_ALLOCATE_STRUCT, GE_RAM_REALLOC_ARRAY

Types: geRam_CriticalCallbackFunction

Changes for Genesis3D v1.6: None

Macros:

GE_RAM_ALLOCATE_ARRAY(type, count);

This is a convenience macro that calls geRam_Allocate to allocate ram for an array of count size of type items.  A pointer is returned to the allocated memory and is pre-cast to the correct type.

Returns: a pointer to the allocated memory, or NULL on failure.

Return to Contents

GE_RAM_ALLOCATE_STRUCT(type);

This is a convenience macro that calls geRam_Allocate to allocate ram for a structure of type type and pre-casts the returned pointer to type.

Returns: a pointer to the allocated memory or NULL on failure.

Return to Contents

GE_RAM_REALLOC_ARRAY(ptr,type,count);

This is a convenience macro that calls geRam_Realloc to adjust the memory pool to accomodate an array of count items of type type at the address ptr.

Return to Contents

Types:

geRam_CriticalCallbackFunction

This is the type of a callback function that can be set using geRam_SetCriticalCallback() to be called when geRam_Allocate is unable to allocate the requested memory.

typedef int (*geRam_CriticalCallbackFunction)( void);

Return to Contents

Functions:

GENESISAPI void geRam_AddAllocation(int n, uint32 size);

This function can be used by programs that use some other memory allocation method but would like to let geRam keep track of statistics of memory usage.  n is the number of allocations to add (or subtract) and size is the amount of memory to add (or subtract).

Return to Contents

GENESISAPI void * geRam_Allocate(uint32 size);

This function allocates the size bytes of memory an returns a pointer to it.

Returns: a pointer to the allocated memory, NULL on error.

Notes:
    from RAM.H: Allocate memory of the given size.  In debug mode, the memory is filled with 0xA5, and we keep track of the amount of memory allocated.  Also, in debug mode, we track where the memory was allocated and can optionally provide a report of allocated blocks.  See geRam_ReportAllocations.
 

Return to Contents

GENESISAPI void * geRam_AllocateClear(uint32 size);

This function allocates size bytes of memory, clears it to 0 and returns a pointer to it.

Returns: a pointer to the allocated memory, or NULL on failure.

Notes:
    from RAM.H: allocate the ram & clear it. (calloc)

Return to Contents

GENESISAPI int geRam_EnableCriticalCallback(int add);

This function increments an internal counter by add (which may be negative).  If the internal counter is greater than 0 and a critical callback function has been set with geRamSetCriticalCallback(), then that function is called if a memory allocation request fails.

Returns: the current counter value after add is applied.

Notes:
    from RAM.H: increments or decrements a counter.  If the counter is 0 the critical callback function (if set) is called for a failed memory allocation.  Add is added to the current counter value.  The new counter value is returned.
 

Return to Contents

GENESISAPI void geRam_Free_( void * ptr);

This function releases memory previously allocated at* ptr.

Returns: nothing.

Notes:
    from RAM.H: Free an allocated memory block.

Return to Contents

geBoolean geRam_IsValidPtr(void * ptr);

This function tests whether ptr is a valid non-NULL pointer using information created by geRam_Allocate.  This function is only available in debug builds.

Returns: GE_TRUE if ptr is valid, GE_FALSE otherwise.

Return to Contents

GENESISAPI void * geRam_Realloc(void * ptr, uint32 newsize);

This function adjusts the size of a previously allocated block of memory at ptr to newsize.  If ptr is NULL, a new memory block is allocated.

Returns: A pointer to the adjusted memory pool, or NULL on failure.

Notes:
    from RAM.H: Reallocate memory.  This function supports shrinking and expanding blocks, and will also act like ram_allocate if the pointer passed to it is NULL. It won't, however, free the memory if you pass it a 0 size.

Return to Contents

GENESISAPI void geRam_ReportAllocations(void);

This function can be called just before exitting to report on any non-freed memory to aid in detecting memory leaks.  This function is only available in debug builds (I think).

Return to Contents

GENESISAPI geRam_CriticalCallbackFunction geRam_SetCriticalCallback(geRam_CriticalCallbackFunction callback);

This function is used to set the critical callback function that will be called if geRam_Allocate() is unable to allocate the requested memory.

Returns: a ptr to the set callback function.

Notes:
    from RAM.H: Set the critical callback function.  ram_allocate will call the critical callback function if it's unable to allocate memory.

Return to Contents