An MDXPool object represents a pool of memory from which blocks can be allocated. More...

Public Member Functions
void	deletePool ()
	Deallocate all memory allocated from the pool, and destroy the pool itself. More...

void	getConfiguration (MDXConfiguration *config)
	Get a copy of the MDXPool's current configuration. More...

void	updateConfiguration (MDXConfiguration *config)
	Update the MDXPool's current configuration. More...

void	malloc (uinta len, void **chunk, uinta flags)
	Allocate one block of memory. More...

void	malloc (uinta len, void *chunk, uinta flags)
	Allocate one block of memory, and get the actual length allocated (which might be larger than the requested length). More...

void	malloc (uinta count, MDXShortMalloc *reqs, uinta flags)
	Allocate memory in bulk, with all blocks having the same flags. More...

void	malloc (uinta count, MDXLongMalloc *reqs)
	Allocate memory in bulk, with different blocks having different flags. More...

void	free (void *chunk)
	Free one block of memory. More...

void	free (uinta count, void **chunks)
	Free memory in bulk. More...

void	innerFree (void innerFreeParam, void chunk)
	Free one block of memory from inside the intercept free callback. This method must only be used from inside of MDXInterceptHandler::mdxInterceptFree(). More...

void	innerFree (void innerFreeParam, uinta count, void *chunks)
	Free memory in bulk from inside the intercept free callback. This method must only be used from inside of MDXInterceptHandler::mdxInterceptFree(). More...

void	makeCollectible (void *chunk)
	Change one block from requiring explicit freeing to being freed by the garbage collector. Sets FLAG_COLLECTABLE. More...

void	makeCollectible (uinta count, void **chunks)
	Change blocks in bulk from requiring explicit freeing to being freed by the garbage collector. Sets FLAG_COLLECTABLE. More...

void	uncacheThread ()
	Reclaim the memory in MDX's cache for the thread calling uncacheThread(). More...

void	triggerGarbageCollection ()
	Trigger garbage collection, even if no thresholds have been reached. More...

void *	checkIntegrity (FILE *fout, bool crashOnError)
	Check the entire MDXPool's structure for internal consistency. More...

void	getStatistics (MDXStatistics *stats)
	Copy the MDXPool's usage statistics to the given MDXStatistics structure. More...

void	dumpPoolStatus (FILE *fout, uinta verbosity)
	Write out the MDXPool's status to the given output. More...

Static Public Member Functions
static void	getDefaultConfiguration (MDXConfiguration *config)
	Fill in an MDXConfiguration structure with the default values. More...

static MDXPool *	createPool (MDXConfiguration *config)
	Create an MDXPool object based on the given configuration. More...

static uinta	getLen (void *chunk)
	Get the length of a block. More...

static void	getLen (uinta count, MDXLen *lens)
	Get the lengths of blocks in bulk. More...

static uinta	getFlags (void *chunk)
	Get the flags associated with a block. More...

static void	getFlags (uinta count, MDXFlags *flags)
	Get block flags in bulk. More...

static bool	isMarked (void *chunk)
	Check if a block is marked (i.e. has FLAG_MARKED set). More...

static void	setOnFreeFlags (void *chunk, uinta flags)
	Set the flags that apply to when a block is freed for one block. More...

static void	setOnFreeFlags (uinta count, MDXFlags *flags)
	Set the flags that apply to when a block is freed in bulk. More...

static bool	mark (void *chunk)
	Mark a block, and return wether or not it was already marked. This method must only be used from inside of MDXMarkingHandler::mdxPerformMarking(). More...

static void	mark (uinta count, void **chunks)
	Mark blocks in bulk. This method must only be used from inside of MDXMarkingHandler::mdxPerformMarking(). More...

static void	formatFlags (FILE *fout, uinta flags)
	Format the flags to the given output. More...

static void	dumpMemory (FILE fout, void floor, void *roof)
	Write a hex dump of the contents of memory to the given output. More...

Static Public Attributes
static const uinta	FLAG_MARKED = 0x002
	The block is marked.

static const uinta	FLAG_COLLECTIBLE = 0x008
	The block is collectible i.e. it will be freed by the grabage collector.

static const uinta	FLAG_INTERCEPT_FREE = 0x010
	Call the intercept free callback instead of freeing the block.

static const uinta	FLAG_FILL_ON_FREE = 0x020
	Fill the block with MDXConfiguration::fillOnFreeByte when it's freed.

static const uinta	FLAG_FILL_ON_MALLOC = 0x100
	Fill the block with MDXConfiguration::fillOnMallocByte when it's first allocated.

static const uinta	FLAG_CHECK_INTEGRITY_EVERY_CALL = 0x800
	WARNING: SLOW. Check the entire pool's internal integrity after every allocation and freeing.

static const uinta	FLAG_ON_FREE_MASK = FLAG_FILL_ON_FREE
	A mask of all the flags that can be set with MDXPool::setOnFreeFlags().

Detailed Description

An MDXPool object represents a pool of memory from which blocks can be allocated.

Use the static method MDXPool::createPool(MDXConfiguration *config) to create an MDXPool object, and use the (non-static) method MDXPool::deletePool() to delete an MDXPool object.

For a general introduction to using MDXPool see the How to Use MDX section.

Note that throughout this API documentation the type uinta means an unsigned integer of the same size as a void pointer.

Member Function Documentation

void * MemoryDividerX::MDXPool::checkIntegrity	(	FILE *	fout,
		bool	crashOnError
	)

Check the entire MDXPool's structure for internal consistency.

This method is intended to help debug memory errors in programs using MDX (and to help debug MDX itself). It's not ment for general use.

Parameters

fout	If internal inconsistency is found then write an error report to this output.
crashOnError	If true then crash upon finding any inconsistency, otherwise continue at your own risk.

Returns: 0 if no inconsistency's found, otherwise an attempt to guess the (non-zero) address of the memory with the wrong contents.

MDXPool * MemoryDividerX::MDXPool::createPool ( MDXConfiguration * config )

static

Create an MDXPool object based on the given configuration.

To use garbage collection MDXConfiguration::markingHandler must be set, and to use finalization MDXConfiguration::markingHandler must be set.

Parameters

config The address of an MDXConfiguration structure containing configuration information foor the new pool.

Returns: The address of the newly created MDXPool object.

void MemoryDividerX::MDXPool::deletePool ( )

Deallocate all memory allocated from the pool, and destroy the pool itself.

It's guarenteed that neither MDXMarkingHandler::mdxPerformMarking() nor MDXInterceptHandler::mdxInterceptFree() will be called after deletePool() returns.

This should be the last call made on any MDXPool, because it finishes by deallocating the memory for the MDXPool object itself.

void MemoryDividerX::MDXPool::dumpMemory	(	FILE *	fout,
		void *	floor,
		void *	roof
	)

static

Write a hex dump of the contents of memory to the given output.

Parameters

fout	Write the hex dump to this output.
floor	The address of the first byte of memory to be dumped.
roof	The address of the byte after the last byte of memory to be dumped.

void MemoryDividerX::MDXPool::dumpPoolStatus	(	FILE *	fout,
		uinta	verbosity
	)

Write out the MDXPool's status to the given output.

Parameters

fout	Write the pool's status to this output.
verbosity	The higher the number, the more information is written out. Valid values are 0, 1, 2 and 3.

void MemoryDividerX::MDXPool::formatFlags	(	FILE *	fout,
		uinta	flags
	)

static

Format the flags to the given output.

Parameters

fout	Write the flags to this output.
flags	The flags to be formatted.

void MemoryDividerX::MDXPool::free ( void * chunk )

Free one block of memory.

Parameters

chunk The address of the block to free.

void MemoryDividerX::MDXPool::free	(	uinta	count,
		void **	chunks
	)

Free memory in bulk.

Parameters

count	The number of blocks to free.
chunks	An array of pointers to the blocks to be freed.

void MemoryDividerX::MDXPool::getConfiguration ( MDXConfiguration * config )

Get a copy of the MDXPool's current configuration.

Parameters

config The address of an MDXConfiguration structure to receive a copy of the MDXPool's current configuration.

void MemoryDividerX::MDXPool::getDefaultConfiguration ( MDXConfiguration * config )

static

Fill in an MDXConfiguration structure with the default values.

This method sets MDXConfiguration::markingHandler and MDXConfiguration::interceptHandler to null. To use garbage collection a markingHandler must be supplied, and to use finalization an interceptHandler must be supplied.

Parameters

config The address of an MDXConfiguration structure to receive the default values.

uinta MemoryDividerX::MDXPool::getFlags ( void * chunk )

static

Get the flags associated with a block.

The following flags are reported: FLAG_MARKED, FLAG_COLLECTABLE, FLAG_INTERCEPT_FREE, FLAG_FILL_ON_FREE and FLAG_FILL_ON_MALLOC. However, the setting of FLAG_MARKED is only reliable from inside of MDXMarkingHandler::mdxPerformMarking().

Parameters

chunk The address of the block to have its flags reported.

Returns: The block's flags.

void MemoryDividerX::MDXPool::getFlags	(	uinta	count,
		MDXFlags *	flags
	)

static

Get block flags in bulk.

The following flags are reported: FLAG_MARKED, FLAG_COLLECTABLE, FLAG_INTERCEPT_FREE, FLAG_FILL_ON_FREE and FLAG_FILL_ON_MALLOC for each block. However, the setting of FLAG_MARKED is only reliable from inside of MDXMarkingHandler::mdxPerformMarking().

Parameters

count	The number of blocks to have their flags reported.
flags	An array of MDXFlags structures of length count. Each block to have its flags reported is described by a structure in this array.

uinta MemoryDividerX::MDXPool::getLen ( void * chunk )

static

Get the length of a block.

Parameters

chunk The address of the block to have its length reported.

Returns: The length of the block.

void MemoryDividerX::MDXPool::getLen	(	uinta	count,
		MDXLen *	lens
	)

static

Get the lengths of blocks in bulk.

Parameters

count	The number of blocks to have their lengths reported.
lens	An array of MDXLen structures of length count. Each block to have its length reported is described by a structure in this array.

void MemoryDividerX::MDXPool::getStatistics ( MDXStatistics * stats )

Copy the MDXPool's usage statistics to the given MDXStatistics structure.

Warning: These statistics are aproximate(!)

Parameters

stats The address of an MDXStatistics structure to receive the MDXPool's statistics.

void MemoryDividerX::MDXPool::innerFree	(	void *	innerFreeParam,
		void *	chunk
	)

Free one block of memory from inside the intercept free callback. This method must only be used from inside of MDXInterceptHandler::mdxInterceptFree().

Parameters

innerFreeParam	The innerFreeParam as passed to MDXInterceptHandler::mdxInterceptFree().
chunk	The address of the block to free.

void MemoryDividerX::MDXPool::innerFree	(	void *	innerFreeParam,
		uinta	count,
		void **	chunks
	)

Free memory in bulk from inside the intercept free callback. This method must only be used from inside of MDXInterceptHandler::mdxInterceptFree().

Parameters

innerFreeParam	The innerFreeParam as passed to MDXInterceptHandler::mdxInterceptFree().
count	The number of blocks to free.
chunks	An array of pointers to the blocks to be freed.

bool MemoryDividerX::MDXPool::isMarked ( void * chunk )

static

Check if a block is marked (i.e. has FLAG_MARKED set).

The value returned by this method, and the setting of FLAG_MARKED in general, are only reliable from inside of MDXMarkingHandler::mdxPerformMarking().

Parameters

chunk The address of the block to be checked for being marked.

Returns: Ture if the block's marked, and false otherwise.

void MemoryDividerX::MDXPool::makeCollectible ( void * chunk )

Change one block from requiring explicit freeing to being freed by the garbage collector. Sets FLAG_COLLECTABLE.

Parameters

chunk The address of the block to be made collectible.

void MemoryDividerX::MDXPool::makeCollectible	(	uinta	count,
		void **	chunks
	)

Change blocks in bulk from requiring explicit freeing to being freed by the garbage collector. Sets FLAG_COLLECTABLE.

Parameters

count	The number of blocks to be made collectible.
chunks	An array of pointers to the blocks to be made collectible.

void MemoryDividerX::MDXPool::malloc	(	uinta	len,
		void **	chunk,
		uinta	flags
	)

Allocate one block of memory.

The following flags may be set: FLAG_COLLECTABLE, FLAG_INTERCEPT_FREE, FLAG_FILL_ON_FREE and FLAG_FILL_ON_MALLOC.

Parameters

len	The number of bytes of memory to allocate.
chunk	A pointer to a pointer where the address of the block is stored.
flags	The flags associated with memory block.

void MemoryDividerX::MDXPool::malloc	(	uinta *	len,
		void **	chunk,
		uinta	flags
	)

Allocate one block of memory, and get the actual length allocated (which might be larger than the requested length).

The following flags may be set: FLAG_COLLECTABLE, FLAG_INTERCEPT_FREE, FLAG_FILL_ON_FREE and FLAG_FILL_ON_MALLOC.

Parameters

len	A pointer to the number of bytes of memory to allocate, afterwards the length actually allocated is returned here.
chunk	A pointer to a pointer where the address of the block is stored.
flags	The flags associated with memory block.

void MemoryDividerX::MDXPool::malloc	(	uinta	count,
		MDXShortMalloc *	reqs,
		uinta	flags
	)

Allocate memory in bulk, with all blocks having the same flags.

The following flags may be set: FLAG_COLLECTABLE, FLAG_INTERCEPT_FREE, FLAG_FILL_ON_FREE and FLAG_FILL_ON_MALLOC.

Parameters

count	The number of blocks to allocate.
reqs	An array of MDXShortMalloc structures of length count. Each block to be allocated is described by a structure in this array.
flags	The flags associated with every memory block in the bulk allocation.

void MemoryDividerX::MDXPool::malloc	(	uinta	count,
		MDXLongMalloc *	reqs
	)

Allocate memory in bulk, with different blocks having different flags.

The following flags may be set: FLAG_COLLECTABLE, FLAG_INTERCEPT_FREE, FLAG_FILL_ON_FREE and FLAG_FILL_ON_MALLOC.

Parameters

count	The number of blocks to allocate.
reqs	An array of MDXLongMalloc structures of length count. Each block to be allocated is described by a structure in this array.

bool MemoryDividerX::MDXPool::mark ( void * chunk )

static

Mark a block, and return wether or not it was already marked. This method must only be used from inside of MDXMarkingHandler::mdxPerformMarking().

Parameters

chunk The address of the block to mark.

Returns: Ture if the block was already marked before mark() was called, and false if it wasn't.

void MemoryDividerX::MDXPool::mark	(	uinta	count,
		void **	chunks
	)

static

Mark blocks in bulk. This method must only be used from inside of MDXMarkingHandler::mdxPerformMarking().

Parameters

count	The number of blocks to mark.
chunks	An array of pointers to the blocks to be marked.

void MemoryDividerX::MDXPool::setOnFreeFlags	(	void *	chunk,
		uinta	flags
	)

static

Set the flags that apply to when a block is freed for one block.

The flags that can be set are those set in the mask FLAG_ON_FREE_MASK, currently this is rather limited.

Parameters

chunk	The address of the block to have its on free flags set.
flags	The flags to set.

void MemoryDividerX::MDXPool::setOnFreeFlags	(	uinta	count,
		MDXFlags *	flags
	)

static

Set the flags that apply to when a block is freed in bulk.

The flags that can be set are those set in the mask FLAG_ON_FREE_MASK, currently this is rather limited.

Parameters

count	The number of blocks to have their on free flags set.
flags	An array of MDXFlags structures of length count. Each block to have its on free flags set is described by a structure in this array.

void MemoryDividerX::MDXPool::triggerGarbageCollection ( )

Trigger garbage collection, even if no thresholds have been reached.

Note that this triggers garbage collection. The collection itself may not even begin until after this method returns, or it may have run to completion before this method returns.

void MemoryDividerX::MDXPool::uncacheThread ( )

Reclaim the memory in MDX's cache for the thread calling uncacheThread().

On Windows all threads must call this after finishing using MDX. On Linux it's optional since the TSD destructor is used to automatically call uncacheThread() when a thread exits.

It's not an error to call uncacheThread() more than once.

It's also not an error for a thread to allocate memory from an MDXPool after calling uncacheThread(). But in this situation MDX creates a new cache for the thread, so uncacheThread() must be called again aftwards to reclaim the new cache.

void MemoryDividerX::MDXPool::updateConfiguration ( MDXConfiguration * config )

Update the MDXPool's current configuration.

The following configuration values are updateable: MDXConfiguration::markingParam, MDXConfiguration::markingHandler, MDXConfiguration::interceptParam and MDXConfiguration::interceptHandler.

Parameters

config The address of an MDXConfiguration structure containing the new configuration values.

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation