The Frame Heap Manager

The Frame Heap Manager is a simple memory manager that can only allocate memory blocks of a specified size while all allocated memory blocks are freed simultaneously. The memory efficiency is favorable because the management information is not contained in the memory block. The following is an overview of the Frame Heap Manager.

Creating Heaps

To use the Frame Heap Manager you must create a frame heap. These functions create and destroy frame heaps.

Functions for Creating and Destroying Heaps
FunctionsFeatures
MEMCreateFrmHeapCreates the frame heap.
MEMCreateFrmHeapExCreates the frame heap. Heap options can be specified.
MEMDestroyFrmHeapDestroys the frame heap.

Allocating Memory Blocks

Allocating and Freeing Memory Blocks

The Frame Heap Manager allocates memory blocks by filling the heap from the top and bottom without any gaps. Because this method is used to allocate memory blocks, there is no heap fragmentation. Because there is no management region for the memory blocks that the Frame Heap Manager allocates, memory is efficiently used and processing for memory block allocation is reduced.


Figure 3-1 Allocating Memory for the Frame Heap

The following functions allocate memory blocks.

Functions for Allocating Memory Blocks
FunctionsFeatures
MEMAllocFromFrmHeapAllocates a memory block from frame heap.
MEMAllocFromFrmHeapExAllocates a memory block from frame heap. The alignment can be specified (described in the next section).

To allocate memory blocks from the end of the heap region, pass a negative value to the alignment argument in the MEMAllocFromFrmHeapEx function.

Allocating the Minimum Memory Block Size

Even though the Frame Heap Manager does not have a memory block management region, allocated memory blocks must be aligned at 4-byte boundaries at a minimum. Allocating a 1-byte memory block consumes 4 bytes of memory.

Specifying Alignment

The Frame Heap Manager can specify alignment during memory block allocation. In the MEMAllocFromFrmHeapEx 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 rear of the heap. The MEMAllocFromFrmHeap function does not specify alignment; the alignment value is always a value of 4.

Freeing Memory Blocks

Because the Frame Heap Manager does not manage individual allocated memory blocks, it cannot deallocate allocated blocks individually. The Frame Heap Manager uses one of the three following methods to deallocate memory blocks.

Methods for Freeing Memory Blocks
MethodContent
Deallocate from the front.Frees memory block groups allocated from the bottom of the heap region.
Deallocate from the rear.Frees memory block groups allocated from the top of the heap region.
Deallocate all.Simultaneously frees all allocated memory blocks from the heap.

The following function frees memory blocks.

Function for Freeing Memory Blocks
FunctionsFeatures
MEMFreeToFrmHeapSimultaneously frees memory blocks using the specified method.

The following deallocation methods can be specified in the MEMFreeToFrmHeap function.

Code Values to Specify in Functions for Freeing Memory Blocks
MethodValue Specified in the Function
Deallocate from the front.MEM_FRMHEAP_FREE_HEAD
Deallocate from the rear.MEM_FRMHEAP_FREE_TAIL
Deallocate all.MEM_FRMHEAP_FREE_ALL (This is equivalent to specifying both MEM_FRMHEAP_FREE_HEAD and MEM_FRMHEAP_FREE_TAIL simultaneously.))

The Frame Heap Manager can also save the memory block allocation status, simultaneously free the memory blocks that are subsequently allocated, and return to the status prior to saving. These features are described in the following section.

Saving and Restoring Memory Block Allocation Status

The Frame Heap Manager allows you to save the memory block allocation status for the heap region and to restore this status later. 20 bytes of memory are necessary for one save of the memory block allocation status. The memory block allocation status can be saved as many times as the heap capacity limit allows. When saving the memory block allocation status, a 4-byte tag can be attached. When restoring the memory block allocation status, the previous status or a status specified by a tag can be restored.


Figure 3-2 Mechanism for Saving and Restoring the Memory Block Allocation Status of a Frame Heap

The following functions save and restore memory block allocation status.

Functions for Saving and Restoring Memory Block Allocation Status
FunctionsFeatures
MEMRecordStateForFrmHeapSaves the memory block allocation status.
MEMFreeByStateToFrmHeapRestores the memory block allocation status.

Adjusting the Heap Region Size

The Frame Heap Manager can reduce the heap region size to match the heap region content. Use this functionality only if memory blocks are not allocated from the rear of the heap region. This functionality can be used to load an indefinite amount of data into memory without leaving gaps in the heap. First, create a heap that has a sufficient size, allocate memory blocks from the bottom of the heap region, and store the data. After all of the required data is stored, reduce the heap region size to match the heap content.


Figure 3-3 Adjusting the Size of the Frame Heap

The following function reduces heap region size.

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

Changing Memory Block Size

The memory block size can be changed with the Frame Heap Manager if the memory block is the last block allocated from the front of the available region in the heap. If the memory block becomes smaller than the current size, the remaining region is merged with the free region above the memory block after reduction. If the memory block becomes larger than the current size, the memory block expands into the free region above the memory block.


Figure 3-4 Changing the Size of Frame Heap Memory Blocks

Use this function to change memory block size.

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

If the available region size is smaller than the specified size when expanding a memory block, the MEMResizeForMBlockFrmHeap function fails and returns zero.

Getting the Allocatable Size

The Frame Heap Manager can obtain the size of the largest allocatable memory block. These functions are shown in the following table.

Functions for Getting the Allocatable Size
FunctionsFeatures
MEMGetAllocatableSizeForFrmHeapGets the maximum size of the allocatable memory block. Alignment is fixed to four.
MEMGetAllocatableSizeForFrmHeapExGets the maximum size of the allocatable memory block. Alignment can be specified.

Revision History

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


CONFIDENTIAL