Memory Divider X
MDX = malloc() + free() + Garbage Collection
 All Classes Namespaces Functions Variables
Public Member Functions | Static Public Member Functions | Static Public Attributes
MemoryDividerX::MDXPool Class Reference

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

List of all members.

Public Member Functions

void deletePool ()
 Deallocate all memory allocated from the pool, and destroy the pool itself.
void getConfiguration (MDXConfiguration *config)
 Get a copy of the MDXPool's current configuration.
void updateConfiguration (MDXConfiguration *config)
 Update the MDXPool's current configuration.
void malloc (uinta len, void **chunk, uinta flags)
 Allocate one block of memory.
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).
void malloc (uinta count, MDXShortMalloc *reqs, uinta flags)
 Allocate memory in bulk, with all blocks having the same flags.
void malloc (uinta count, MDXLongMalloc *reqs)
 Allocate memory in bulk, with different blocks having different flags.
void free (void *chunk)
 Free one block of memory.
void free (uinta count, void **chunks)
 Free memory in bulk.
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().
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().
uinta getLen (void *chunk)
 Get the length of a block.
void getLen (uinta count, MDXLen *lens)
 Get the lengths of blocks in bulk.
uinta getFlags (void *chunk)
 Get the flags associated with a block.
void getFlags (uinta count, MDXFlags *flags)
 Get block flags in bulk.
bool isMarked (void *chunk)
 Check if a block is marked (i.e. has FLAG_MARKED set).
void setOnFreeFlags (void *chunk, uinta flags)
 Set the flags that apply to when a block is freed for one block.
void setOnFreeFlags (uinta count, MDXFlags *flags)
 Set the flags that apply to when a block is freed in bulk.
void makeCollectible (void *chunk)
 Change one block from requiring explicit freeing to being freed by the garbage collector. Sets FLAG_COLLECTABLE.
void makeCollectible (uinta count, void **chunks)
 Change blocks in bulk from requiring explicit freeing to being freed by the garbage collector. Sets FLAG_COLLECTABLE.
void mark (void *chunk)
 Mark a block. This method must only be used from inside of MDXMarkingHandler::mdxPerformMarking().
void mark (uinta count, void **chunks)
 Mark blocks in bulk. This method must only be used from inside of MDXMarkingHandler::mdxPerformMarking().
void uncacheThread ()
 Reclaim the memory in MDX's cache for the thread calling uncacheThread().
void triggerGarbageCollection ()
 Trigger garbage collection, even if no thresholds have been reached.
void * checkIntegrity (FILE *fout, bool crashOnError)
 Check the entire MDXPool's structure for internal consistency.
void getStatistics (MDXStatistics *stats)
 Copy the MDXPool's usage statistics to the given MDXStatistics structure.
void dumpPoolStatus (FILE *fout, uinta verbosity)
 Write out the MDXPool's status to the given output.

Static Public Member Functions

static void getDefaultConfiguration (MDXConfiguration *config)
 Fill in an MDXConfiguration structure with the default values.
static MDXPoolcreatePool (MDXConfiguration *config)
 Create an MDXPool object based on the given configuration.
static void formatFlags (FILE *fout, uinta flags)
 Format the flags to the given output.
static void dumpMemory (FILE *fout, void *floor, void *roof)
 Write a hex dump of the contents of memory to the given output.

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:
foutIf internal inconsistency is found then write an error report to this output.
crashOnErrorIf 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.

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:
configThe address of an MDXConfiguration structure containing configuration information foor the new pool.
Returns:
The address of the newly created MDXPool object.

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:
foutWrite the hex dump to this output.
floorThe address of the first byte of memory to be dumped.
roofThe 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:
foutWrite the pool's status to this output.
verbosityThe 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:
foutWrite the flags to this output.
flagsThe flags to be formatted.
void MemoryDividerX::MDXPool::free ( void *  chunk)

Free one block of memory.

Parameters:
chunkThe address of the block to free.
void MemoryDividerX::MDXPool::free ( uinta  count,
void **  chunks 
)

Free memory in bulk.

Parameters:
countThe number of blocks to free.
chunksAn array of pointers to the blocks to be freed.

Get a copy of the MDXPool's current configuration.

Parameters:
configThe address of an MDXConfiguration structure to receive a copy of the MDXPool's current configuration.

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:
configThe address of an MDXConfiguration structure to receive the default values.
uinta MemoryDividerX::MDXPool::getFlags ( void *  chunk)

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:
chunkThe address of the block to have its flags reported.
Returns:
The block's flags.
void MemoryDividerX::MDXPool::getFlags ( uinta  count,
MDXFlags flags 
)

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:
countThe number of blocks to have their flags reported.
flagsAn 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)

Get the length of a block.

Parameters:
chunkThe address of the block to have its length reported.
Returns:
The length of the block.
void MemoryDividerX::MDXPool::getLen ( uinta  count,
MDXLen lens 
)

Get the lengths of blocks in bulk.

Parameters:
countThe number of blocks to have their lengths reported.
lensAn array of MDXLen structures of length count. Each block to have its length reported is described by a structure in this array.

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

Warning: These statistics are aproximate(!)

Parameters:
statsThe 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:
innerFreeParamThe innerFreeParam as passed to MDXInterceptHandler::mdxInterceptFree().
chunkThe 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:
innerFreeParamThe innerFreeParam as passed to MDXInterceptHandler::mdxInterceptFree().
countThe number of blocks to free.
chunksAn array of pointers to the blocks to be freed.
bool MemoryDividerX::MDXPool::isMarked ( void *  chunk)

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:
chunkThe address of the block to be checked for being marked.
Returns:
Ture if the block's marked, and false otherwise.

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

Parameters:
chunkThe 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:
countThe number of blocks to be made collectible.
chunksAn 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:
lenThe number of bytes of memory to allocate.
chunkA pointer to a pointer where the address of the block is stored.
flagsThe 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:
lenA pointer to the number of bytes of memory to allocate, afterwards the length actually allocated is returned here.
chunkA pointer to a pointer where the address of the block is stored.
flagsThe 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:
countThe number of blocks to allocate.
reqsAn array of MDXShortMalloc structures of length count. Each block to be allocated is described by a structure in this array.
flagsThe 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:
countThe number of blocks to allocate.
reqsAn array of MDXLongMalloc structures of length count. Each block to be allocated is described by a structure in this array.
void MemoryDividerX::MDXPool::mark ( void *  chunk)

Mark a block. This method must only be used from inside of MDXMarkingHandler::mdxPerformMarking().

Parameters:
chunkThe address of the block to mark.
void MemoryDividerX::MDXPool::mark ( uinta  count,
void **  chunks 
)

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

Parameters:
countThe number of blocks to mark.
chunksAn array of pointers to the blocks to be marked.
void MemoryDividerX::MDXPool::setOnFreeFlags ( void *  chunk,
uinta  flags 
)

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:
chunkThe address of the block to have its on free flags set.
flagsThe flags to set.
void MemoryDividerX::MDXPool::setOnFreeFlags ( uinta  count,
MDXFlags flags 
)

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:
countThe number of blocks to have their on free flags set.
flagsAn array of MDXFlags structures of length count. Each block to have its on free flags set is described by a structure in this array.

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.

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.

Update the MDXPool's current configuration.

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

Parameters:
configThe address of an MDXConfiguration structure containing the new configuration values.
 All Classes Namespaces Functions Variables