The Expanded Heap Manager

The Expanded Heap Manager is a memory manager that allows you to freely allocate and deallocate memory, similar to the C standard library malloc and free functions. In addition to allocating and freeing memory, this manager has additional functions for game programs. The following is an overview of the Expanded Heap Manager.

Creating Heaps

To use the Expanded Heap Manager, first create an expanded heap. The following functions create and destroy expanded heaps.

Functions to Create and Destroy Expanded Heaps
MEMCreateExpHeapCreates the expanded heap.
MEMCreateExpHeapExCreates the expanded heap. Heap options can be specified.
MEMDestroyExpHeapDestroys the expanded heap.

Allocating Memory Blocks

Allocating and Freeing Memory Blocks

The following functions allocate and free memory blocks.

Functions for Allocating and Freeing Memory Blocks
MEMAllocFromExpHeapAllocates a memory block from the expanded heap.
MEMAllocFromExpHeapExAllocates a memory block from the expanded heap. The alignment can be specified (described in the next section).
MEMFreeToExpHeapDeallocates a memory block.

Allocating the Minimum Memory Block Size

The Expanded Heap Manager needs 16 bytes to use as a memory block management region. The minimum alignment of allocated memory blocks must be on a 4-byte boundary; even if a one-byte memory block is allocated, 20 bytes of memory are consumed.

Procedure for Allocating Memory Blocks

The Expanded Heap Manager has two modes that identify available regions for allocating memory blocks. You can switch between modes. These modes are described below.

Memory Block Allocation Modes
FIRST ModeAllocates a memory block from the first free region that is at least the size of the memory block to allocate.
NEAR ModeSearches for a free region nearest in size to the memory block to allocate, then allocates the memory block from this free region.

Figure 2-1 Procedure for Allocating Expanded Heap Memory Blocks

FIRST is the default mode. Unlike FIRST, NEAR allocates an available block nearest in size to the memory block to allocate. If an exact match is not found, this mode searches all free regions for the nearest match. Therefore, memory block allocation takes longer if free regions are fragmented. The following functions set and acquire the allocation mode.

Functions for Setting and Getting Allocation Modes
MEMSetAllocModeForExpHeapSets the allocation mode.
MEMGetAllocModeForExpHeapGets the current allocation mode.

The following are the allocation mode types that different functions use.

Allocation Mode Types That Functions Use
Mode Value Specified by the Function

Allocating Memory Blocks from the Top of the Heap Region

Generally, the Expanded Heap Manager searches for free regions from the lowest to highest address in the heap region and allocates memory blocks to the free regions starting from the bottom. As an alternative, you can search for free regions from the highest to lowest address in the heap. Using this feature, you can allocate longer-term memory blocks from the beginning of the heap region, and temporary memory blocks from the end of the heap region to help minimize heap fragmentation. For example, you can use this feature to load compressed data into memory, expand the compressed data, and then delete the compressed data source. In this case, if the expansion process is performed by allocating the memory block from the bottom of the heap region as usual, the free region will be divided into two.

Figure 2-2 Mechanism for Segmenting Memory Blocks

In contrast, if you temporarily load the compressed data into a memory block allocated from the top of the heap region, the free region is not divided.

Figure 2-3 Method for Segmenting Expanded Heap Memory Blocks

To allocate memory blocks from the top of the heap region, use the memory block allocation function, MEMAllocFromExpHeapEx, and pass a negative value to the alignment argument (described below).

Specifying Alignment

The Expanded Heap Manager specifies alignment during memory block allocation. In the MEMAllocFromExpHeapEx function, you can specify 4, 8, 16 or 32 as alignment values. If negative values (i.e., -4, -8, -16 or -32) are specified, memory blocks are allocated from the top of the heap. The MEMAllocFromExpHeap function does not specify an alignment; the alignment value is always 4.

By default, the small memory fragments produced by alignment are not reused as allocatable memory. To allocate this fragmentary memory as valid regions, enable its reuse with the MEMUseMarginOfAlignmentForExpHeap function. However, note that performance may decline if a large number of memory fragments are registered.

Adjusting the Heap Region Size

The Expanded Heap Manager can reduce the heap region size to match the heap content. Use this functionality only if memory blocks are not allocated from the top of the heap region. Also note that regions of free memory that are closer to the bottom than the already allocated memory blocks are not reduced in size and remain unchanged.

After placing data of undefined size and number in memory, this feature can be used to optimize the heap size when allocating additional memory is not required. First, create an extended heap with a sufficient size, allocate memory blocks from the heap region, and store the data. After storing all the required data and freeing all memory blocks allocated from the top of the heap region, reduce the heap size to match its content.

Figure 2-4 Adjusting the Size of the Extended Heap

The following function reduces heap region size.

Function for Reducing the Size of the Heap Region
MEMAdjustExpHeapReduces the size of the heap region by freeing unused regions at the top of the heap region.

Changing Memory Block Size

The Expanded Heap Manager can change the size of the allocated memory blocks without moving them. If a memory block is reduced to a size smaller than it originally was, the leftover region is used as a free region. If a memory block is expanded to a size larger than it originally was, it must have sufficient free space available above it for this to happen. If there is a free region above a memory block, this function merges the free region with the memory block to increase the size of the memory block.

Figure 2-5 Changing the Size of Expanded Heap Memory Blocks

Use this function to change memory block size.

Function for Changing the Size of Memory Blocks
MEMResizeForMBlockExpHeapExpands or reduces memory blocks. Returns the changed memory block size.

When reducing memory blocks, if the specified memory block size is only slightly different from the current actual memory block size, then the free region that would be created after this block is reduced, occasionally cannot be used effectively. In such cases, the MEMResizeForMBlockExpHeap function leaves the memory block's size unchanged and returns the current actual memory block size. If you attempt to expand a memory block when either there is no free region directly above the memory block, or it was not possible to achieve the desired size even after merging the current memory block with the free region above it, the MEMResizeForMBlockExpHeap function fails and returns zero.

Acquiring Free Space

The Expanded Heap Manager can get the total amount of available regions. It can also obtain the size of the largest allocatable memory block. These functions are shown in the following table.

Functions for Acquiring Free Memory
MEMGetTotalFreeSizeForExpHeapGets the total size of all available regions in the expanded heap.
MEMGetAllocatableSizeForExpHeapGets the size of the maximum allocatable memory block. Alignment is fixed to four.
MEMGetAllocatableSizeForExpHeapExGets the size of the maximum allocatable memory block. Alignment can be specified.

Group IDs

When the Expanded Heap Manager allocates memory blocks, group IDs from 0 through 255 are stored in the memory block management region. A group ID can be modified as necessary. When a group ID is changed, the change occurs during the next memory block allocation. The group ID is used for the following purposes.

The following functions set and get group IDs.

Functions for Setting and Getting Group IDs
MEMSetGroupIDForExpHeapSets the group ID of the expanded heap.
MEMGetGroupIDForExpHeapGets the group ID of the expanded heap.

Processes for Memory Blocks

The Expanded Heap Manager can perform user-specified processes on the allocated memory block. With this functionality, you can perform various processes on the heap that are not already prepared in the Expanded Heap Manager. Below are some examples.

Functions that can cause a specified process to be performed are as follows.

MEMVisitAllocatedForExpHeapCalls a user-specified function for each allocated memory block.

Getting Memory Block Information

The Expanded Heap Manager can get allocated memory block information that indicates memory block size, group ID, and whether the allocated memory blocks were allocated from the lowest or highest address. The functions that get memory block information are shown below.

Functions for Getting Memory Block Information
MEMGetSizeForMBlockExpHeapGets the size of the memory block.
MEMGetGroupIDForMBlockExpHeapGets the group ID of the memory block.
MEMGetAllocDirForMBlockExpHeapGets the allocation direction of the memory block.

Checking Heaps and Memory Blocks

The Expanded Heap Manager can check whether the expanded heap and allocated memory blocks from the expanded heap are destroyed. The functions that check expanded heaps and memory blocks are shown below.

Functions that Check Extended Heaps and Memory Blocks
MEMCheckExpHeapDetermines whether the extended heap is destroyed.
MEMCheckForMBlockExpHeapDetermines whether a memory block is destroyed.

Revision History

2013/05/08 Automated cleanup pass.
2010/11/01 Initial version.