CRM64Pro GDK  v0.97
A free cross-platform game development kit built on top of SDL 2.0
Functions
Memory Manager

Functions

void CRM64Pro::CMem::setVerboseSampleInterval (Sint32 iInterval)
 
void CRM64Pro::CMem::setLogLevel (eMemStatsLevel eMSL)
 
void * CRM64Pro::CMem::alloc (size_t iSize, Uint32 iModule)
 
void * CRM64Pro::CMem::calloc (size_t iNum, size_t iSize, Uint32 iModule)
 
void * CRM64Pro::CMem::realloc (void *pMem, size_t iSize, Uint32 iModule)
 
void * CRM64Pro::CMem::alloc_aligned (size_t iSize, size_t iAlign, Uint32 iModule)
 
void CRM64Pro::CMem::free (void *pMem)
 
void CRM64Pro::CMem::free_aligned (void *pMem)
 
void CRM64Pro::CMem::destroy ()
 
Sint32 CRM64Pro::CMem::info (Sint32 iMode)
 

Detailed Description

CRM64Pro Memory Manager(CMem) provides a high performance and thread-safe functions for allocating memory blocks. It also helps to reduce memory fragmentation.
All CRM64Pro GDK modules and external libs (SDL2, libpng, etc.) are using CMem for allocation/deallocation memory.
The client application can use CMem too and could define different module number for having precise and separated statistics.

CMem is composed of three different functional layers:

CRM64Pro_MemoryManager.png
CMem functional layers

For setting the memory stats gathering level, you should call to setLogLevel() before calling any other function on your main function in order to capture all information, but you could modify the gathering level at any point just keep in mind that once you call info(), it will dump the information based on current active mode.
Calling destroy() is optional as modern operating system will free all allocated memory but in any case, advised. Call it at the very end of your application, right before the last return instruction. Another option is to use atexit(CMem::destroy) function.

Note
CRM64Pro STL containers are using CMem allocator so they are not fully compatible with standard STL containers, in these cases, specific transformations are needed.
For example in case of string:
CRM64Pro::string sSource = "mySourceValue;
std::string sDest = sSource; –> Will fail
std::string sDest = sSource.c_str(); –> OK
Warning
If new/delete operators are globally overrided, the stats gathering level must be set to MSL_NULL.

Enumeration Type Documentation

◆ eMemStatsLevel

Memory stats gathering level.

Enumerator
MSL_NULL 

Disable memory stats gathering. Default value in release code.

MSL_NORMAL 

Normal memory stats gathering. CRM64Pro modules and user allocations are shown individually. Default value in debug mode.

MSL_HIGH 

High memory stats gathering. MSL_NORMAL level plus deallocations are shown for each module.

MSL_VERBOSE 

Verbose memory stats gathering. MSL_HIGH level plus: evolution of allocated memory per module (CMem-Evolution.csv output file) and memory request size histogram per module (CMem-Histogram.csv).

Function Documentation

◆ setVerboseSampleInterval()

HandleDLL void CRM64Pro::CMem::setVerboseSampleInterval ( Sint32  iInterval)

Set time interval between each sample when the stats level is MSL_VERBOSE.

Parameters
iIntervalinteger with time in milliseconds [1, 30000].

◆ setLogLevel()

HandleDLL void CRM64Pro::CMem::setLogLevel ( eMemStatsLevel  eMSL)

Set the stats gathering level.

Parameters
eMSLstats gathering level. For further information, please check eMemStatsLevel enum.

◆ alloc()

HandleDLL void * CRM64Pro::CMem::alloc ( size_t  iSize,
Uint32  iModule 
)

Reserve a memory block using C64 Memory Manager.

It is automatically aligned to 4 in 32bits mode and 16 for 64 bits mode.

Parameters
iSizesize of the memory block, in bytes.
iModuleused for storing who requested the memory for statistics results.
Returns
A pointer to the reserved memory block.
Note
It is a replacement of standard malloc() function.

◆ calloc()

HandleDLL void * CRM64Pro::CMem::calloc ( size_t  iNum,
size_t  iSize,
Uint32  iModule 
)

Reserve a memory block using C64 Memory Manager and reset it to 0.

It is automatically aligned to 4 in 32bits mode and 16 for 64 bits mode.

Parameters
iNumnumber of elements to allocate.
iSizesize of each element.
iModuleused for storing who requested the memory for statistics results.
Returns
A pointer to the reserved memory block.
Note
It is a replacement of standard calloc() function.

◆ realloc()

HandleDLL void * CRM64Pro::CMem::realloc ( void *  pMem,
size_t  iSize,
Uint32  iModule 
)

Reallocate a memory block using C64 Memory Manager.

It is automatically aligned to 4 in 32bits mode and 16 for 64 bits mode.

Parameters
pMempointer to the memory area to be reallocated.
iSizesize of the memory block, in bytes.
iModuleused for storing who requested the memory for statistics results.
Returns
A pointer to the reserved memory block.
Note
It is a replacement of standard realloc() function.

◆ alloc_aligned()

HandleDLL void * CRM64Pro::CMem::alloc_aligned ( size_t  iSize,
size_t  iAlign,
Uint32  iModule 
)

Reserve a memory block using C64 Memory Manager aligned to the desired value.

Parameters
iSizesize of the memory block, in bytes.
iAlignspecifies the alignment. Must be a valid alignment supported by the implementation. Usually a 2^n number is supported.
iModuleused for storing who requested the memory for statistics results.
Returns
A pointer to the reserved memory block.
Note
It is a replacement of standard aligned_alloc() function.

◆ free()

HandleDLL void CRM64Pro::CMem::free ( void *  pMem)

Deallocate a memory block using C64 Memory Manager.

Parameters
pMempointer to a memory block previously allocated with alloc(), calloc() or realloc().
Note
It is a replacement of standard free() function.

◆ free_aligned()

HandleDLL void CRM64Pro::CMem::free_aligned ( void *  pMem)

Deallocate a memory block using C64 Memory Manager.

Parameters
pMempointer to a memory block previously allocated with alloc_aligned().
Note
It is a replacement of standard free() function.

◆ destroy()

HandleDLL void CRM64Pro::CMem::destroy ( )

Destroy all pooled memory used by the Low-Level Allocator.

Use it carefully as all allocations will be invalid after calling this method. It can be safely called at the very end of your appliation although if there is any STL container statically constructed, an error will happen. For these cases you can either reduce the scope of the STL container or use atexit() function.

Note
In any case, modern operating systems will free and destroy all assigned memory once the application exists but a memory debugger will detect the leak.

◆ info()

HandleDLL Sint32 CRM64Pro::CMem::info ( Sint32  iMode)

Output useful information about the memory usage.

Parameters
iMode1 for displaying extra information about the Low-Level Allocator (default value) or 0 for disabling it.
Returns
0 on success or a negative error code on failure.
Note
The output of this function uses the mode set by the default log (LM_NULL, LM_STDOUT, LM_FILE, LM_FILEAPPEND or LM_CONSOLE) and depends on the eMemStatsLevel level set.