Memory Manager

Detailed Description

v2.00 (26 June 2023)
Memory Manager module providing a very high performance and thread-safe memory allocation functions.

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 specific statistics.

CMem is composed of three different functional layers:

CMem functional layers

• FrontEnd functions: alloc(), calloc(), realloc(), alloc_aligned(), free(), free_aligned(), setLogLevel(), setVerboseSampleInterval(), info() and destroy()
• Memory stats system providing information for each module:
  • CRM64Pro interfaces, managers and objects.
  • CRM64Pro STL containers.
  • CRM64Pro network system.
  • TinyXML2 library.
  • SDL3 libraries.
  • ModPlug library.
  • Ogg library.
  • FLAC library.
  • MP3 library.
  • PNG library.
  • zlib and zlib-ng libraries.
  • User custom modules.
  In MSL_VERBOSE mode, two CSV files are produced, one with the histogram of all the allocation sizes by module and a second one, with the evolution of the memory allocation size during the application execution for each module. In this case a "snapshot" is taken every a time interval, by default it is set to 0.5 seconds but can be modified using setVerboseSampleInterval() function.
• Low-Level Allocator. Currently, there are two options with more coming in the future. You can easily add any other allocator as VMem, nedmalloc, etc.
  • Standard C/C++ allocator: the standard allocator, not very high performance but it is thread-safe and has no memory overhead at all.
  • ltalloc: a modified version of ltalloc allocator providing a very high performance, thread-safe but with some memory overhead.
    This allocator requests memory to the operating system in 1MB blocks and automatically creates memory pools for 16B, 32B, 64B, 128B, 256B, 512B, 1KB, 2KB, 4KB, 8KB, 16KB, 32KB, 64KB, 128KB, 256KB and 512KB memory requests. For requests greater than 512KB, a direct call to the operating system is executed. This means that a single call for allocating 16B will actually reserve 1MB from the operating system so this could cause some overhead. In addition, any request is rounded to the closest upper 2^n pool size, so a request of 200B will use a slot from the 256B pool and 56B are "lost" in overhead.

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

new/delete global operators are not overrided, it could be done defining C64_OVERRIDE_NEW flag but it must be used carefully.

Warning

If new/delete operators are globally overrided, the stats gathering level must be set to MSL_NULL.

Enumerations
enum	CRM64Pro::CMem::eMemStatsLevel { CRM64Pro::CMem::MSL_NULL = 0 , CRM64Pro::CMem::MSL_NORMAL = 2 , CRM64Pro::CMem::MSL_HIGH = 4 , CRM64Pro::CMem::MSL_VERBOSE = 8 }
	Memory stats gathering level. More...

Functions
void	CRM64Pro::CMem::setVerboseSampleInterval (Sint32 iInterval)
	Set time interval between each sample when the stats level is MSL_VERBOSE. By default it is set to 500ms.
void	CRM64Pro::CMem::setLogLevel (eMemStatsLevel eMSL)
	Set the memory stats gathering level.
void	CRM64Pro::CMem::setMsgOutput (Sint32 iLM, const char *szFile)
	Set the memory log mode.
Sint32	CRM64Pro::CMem::setModuleName (Uint32 iModule, const char *szName)
	Set the memory log mode.
void *	CRM64Pro::CMem::alloc (size_t iSize, Uint32 iModule)
	Reserve a memory block using C64 Memory Manager.
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.
void *	CRM64Pro::CMem::realloc (void *pMem, size_t iSize, Uint32 iModule)
	Reallocate a memory block using C64 Memory Manager.
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.
void	CRM64Pro::CMem::free (void *pMem)
	Deallocate a memory block using C64 Memory Manager.
void	CRM64Pro::CMem::free_aligned (void *pMem)
	Deallocate a memory block using C64 Memory Manager.
void	CRM64Pro::CMem::destroy ()
	Destroy all internal memory used by the Low-Level Allocator.
Sint32	CRM64Pro::CMem::info (Sint32 iMode)
	Output useful information about the memory usage.

Enumeration Type Documentation

eMemStatsLevel

enum CRM64Pro::CMem::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. By default it is set to 500ms.

Parameters

iInterval

integer with time in milliseconds [1, 30000].

setLogLevel()

HandleDLL void CRM64Pro::CMem::setLogLevel

(

eMemStatsLevel

eMSL

)

Set the memory stats gathering level.

Note

The memory stats level must be set before any other call to CRM64Pro (including custom STL containers), ideally, it should be the first line on the main funtion.

Parameters

eMSL	stats gathering level. For further information, please check eMemStatsLevel enum.

setMsgOutput()

HandleDLL void CRM64Pro::CMem::setMsgOutput	(	Sint32	iLM,
		const char *	szFile
	)

Set the memory log mode.

Parameters

iLM	log mode for memory stats. Check LM_NULL, LM_STDOUT, LM_FILE, LM_FILEAPPEND and LM_CONSOLE for further information.
szFile	name of log file (only makes sense with LM_FILE or LM_FILEAPPEND). Directory separators '\' and '/' are supported.

Note

Usually, this method is not required to be used as the memory stats output uses as a baseline the same configuration of the generic C64 log system.
It is useful when the C64 log system is not initiated but we still want to see the memory stats output.

setModuleName()

HandleDLL Sint32 CRM64Pro::CMem::setModuleName	(	Uint32	iModule,
		const char *	szName
	)

Set the memory log mode.

Parameters

iModule	used for storing who requested the memory for statistics results. Only for custom user modules.
szName	name of the custom user module. By default, all custom user modules are shown as "User".

Returns

0 on success or a negative error code on failure.

Note

For renaming a custom user module, just call this method again.

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

iSize	size of the memory block, in bytes.
iModule	used 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

iNum	number of elements to allocate.
iSize	size of each element.
iModule	used 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

pMem	pointer to the memory area to be reallocated.
iSize	size of the memory block, in bytes.
iModule	used 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

iSize	size of the memory block, in bytes.
iAlign	specifies the alignment. Must be a valid alignment supported by the implementation. Usually a 2^n number is supported.
iModule	used 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

pMem	pointer 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

pMem	pointer 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 internal memory used by the Low-Level Allocator.

Only applicable when using a Low-Level Allocator. It also call info() for displaying memory stats.

Warning

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

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

iMode

1 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.