1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META http-equiv="Content-Style-Type" content="text/css"> 6<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 8.0.0.0 for Windows"> 7<TITLE>The Frame Heap Manager</TITLE> 8<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 9</HEAD> 10<BODY> 11 12<H1>The Frame Heap Manager</H1> 13<p> 14The 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. Furthermore, the memory efficiency is good because the management information is not contained in the memory block. The following is an overview of the Frame Heap Manager. 15</p> 16 17<H2>Creating Heaps</H2> 18<p> 19To use the Frame Heap Manager you must create a frame heap. These functions create and destroy frame heaps. 20</p> 21 22<TABLE border="1"><CAPTION>Functions for Creating and Destroying Heaps</CAPTION> 23<TR><TD>Functions</TD><TD>Functions</TD></TR> 24<TR><TD><A HREF="./FrmHeap/MEMCreateFrmHeap.html"><CODE>MEMCreateFrmHeap</CODE></A></TD><TD>Creates the frame heap.</TD></TR> 25<TR><TD><A HREF="./FrmHeap/MEMCreateFrmHeapEx.html"><CODE>MEMCreateFrmHeapEx</CODE></A></TD><TD>Creates the frame heap. Heap options can be specified.</TD></TR> 26<TR><TD><A HREF="./FrmHeap/MEMDestroyFrmHeap.html"><CODE>MEMDestroyFrmHeap</CODE></A></TD><TD>Destroys the frame heap.</TD></TR> 27</TABLE> 28 29<H2>Allocating Memory Blocks</H2> 30<H3>Allocating and Freeing Memory Blocks</H3> 31<p> 32The 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. Furthermore, 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. 33</p> 34 35<CENTER><IMG SRC="./fig3-1.gif"><BR>Figure 3-1 Allocating Memory for the Frame Heap<BR></CENTER> 36 37<p> 38The following functions alblocate memory blocks. 39</p> 40 41<TABLE border="1"><CAPTION>Functions for Allocating Memory Blocks</CAPTION> 42<TR><TD>Functions</TD><TD>Functions</TD></TR> 43<TR><TD><A HREF="./FrmHeap/MEMAllocFromFrmHeap.html"><CODE>MEMAllocFromFrmHeap</CODE></A></TD><TD>Allocates a memory block from frame heap.</TD></TR> 44<TR><TD><A HREF="./FrmHeap/MEMAllocFromFrmHeapEx.html"><CODE>MEMAllocFromFrmHeapEx</CODE></A></TD><TD>Allocates a memory block from frame heap. The alignment can be specified (described in the next section).</TD></TR> 45</TABLE> 46 47<p> 48To allocate memory blocks from the top of the heap region, pass a negative value to the alignment argument in the <A HREF="./FrmHeap/MEMAllocFromFrmHeapEx.html"><CODE>MEMAllocFromFrmHeapEx</CODE></A> function. 49</p> 50 51<H3>Allocating the Minimum Memory Block Size</H3> 52<p> 53Even 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. 54</p> 55 56<H2>Specifying Alignment</H2> 57<p> 58The Frame Heap Manager can specify alignment during memory block allocation. In the <A HREF="./FrmHeap/MEMAllocFromFrmHeapEx.html"><CODE>MEMAllocFromFrmHeapEx</CODE></A> 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 <A HREF="./FrmHeap/MEMAllocFromFrmHeap.html"><CODE>MEMAllocFromFrmHeap</CODE></A> function does not specify alignment; the alignment value is always a value of 4. 59</p> 60 61<H2>Freeing Memory Blocks</H2> 62<p> 63Because the Frame Heap Manager does not manage individual allocated memory blocks, it cannot free allocated blocks individually. The Frame Heap Manager uses one of the three following methods to free memory blocks. 64</p> 65 66<TABLE border="1"><CAPTION>Methods for Freeing Memory Blocks</CAPTION> 67<TR><TD>Method</TD><TD>Content</TD></TR> 68<TR><TD>Free from the bottom.</TD><TD>Frees memory block groups allocated from the bottom of the heap region.</TD></TR> 69<TR><TD>Free from the top.</TD><TD>Frees memory block groups allocated from the top of the heap region.</TD></TR> 70<TR><TD>Free all.</TD><TD>Simultaneously frees all allocated memory blocks from the heap.</TD></TR> 71</TABLE> 72 73<p> 74The following function frees memory blocks. 75</p> 76 77<TABLE border="1"><CAPTION>Function for Freeing Memory Blocks</CAPTION> 78<TR><TD>Functions</TD><TD>Functions</TD></TR> 79<TR><TD><A HREF="./FrmHeap/MEMFreeToFrmHeap.html"><CODE>MEMFreeToFrmHeap</CODE></A></TD><TD>Simultaneously frees memory blocks using the specified method.</TD></TR> 80</TABLE> 81 82<p> 83The following methods can be specified in the <A HREF="./FrmHeap/MEMFreeToFrmHeap.html"><CODE>MEMFreeToFrmHeap</CODE></A> function. 84</p> 85 86<TABLE border="1"><CAPTION>Code Values to Specify in Functions for Freeing Memory Blocks</CAPTION> 87<TR><TD>Method</TD><TD>Value Specified in the Function</TD></TR> 88<TR><TD>Free from the bottom.</TD><TD><CODE>MEM_FRMHEAP_FREE_HEAD</CODE></TD></TR> 89<TR><TD>Free from the top.</TD><TD><CODE>MEM_FRMHEAP_FREE_TAIL</CODE></TD></TR> 90<TR><TD>Free all.</TD><TD><CODE>MEM_FRMHEAP_FREE_ALL</CODE> (this code value has the same effect as simultaneously setting <CODE>MEM_FRMHEAP_FREE_HEAD</CODE> and <CODE>MEM_FRMHEAP_FREE_TAIL</CODE>.)</TD></TR> 91</TABLE> 92 93<p> 94The 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. 95</p> 96 97<H2>Saving and Restoring Memory Block Allocation Status</H2> 98<p> 99The 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 saving each 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. 100</p> 101 102<CENTER><IMG SRC="./fig3-2.gif"><BR>Figure 3-2 Mechanism for Saving and Restoring the Memory Block Allocation Status of a Frame Heap<BR></CENTER> 103 104<p> 105The following functions save and restore memory block allocation status. 106</p> 107 108<TABLE border="1"><CAPTION>Functions for Saving and Restoring Memory Block Allocation Status</CAPTION> 109<TR><TD>Functions</TD><TD>Functions</TD></TR> 110<TR><TD><A HREF="./FrmHeap/MEMRecordStateForFrmHeap.html"><CODE>MEMRecordStateForFrmHeap</CODE></A></TD><TD>Saves the memory block allocation status.</TD></TR> 111<TR><TD><A HREF="./FrmHeap/MEMFreeByStateToFrmHeap.html"><CODE>MEMFreeByStateToFrmHeap</CODE></A></TD><TD>Restores the memory block allocation status.</TD></TR> 112</TABLE> 113 114<H2>Adjusting the Heap Region Size</H2> 115<p> 116The Frame Heap Manager can reduce the heap region size to match the heap region content. Only use this functionality if memory blocks haven't been allocated from the top 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. 117</p> 118 119<CENTER><IMG SRC="./fig3-3.gif"><BR>Figure 3-3 Adjusting the Size of the Frame Heap<BR></CENTER> 120The following function reduces heap region size. 121<TABLE border="1"><CAPTION>Function for Reducing the Size of the Heap Region</CAPTION> 122<TR><TD>Functions</TD><TD>Functions</TD></TR> 123<TR><TD><A HREF="./FrmHeap/MEMAdjustFrmHeap.html"><CODE>MEMAdjustFrmHeap</CODE></A></TD><TD>Reduces the size of the heap region by freeing unused regions at the top of the heap region.</TD></TR> 124</TABLE> 125 126<H2>Changing Memory Block Size</H2> 127<p> 128The memory block size can be changed with the Frame Heap Manager if the memory block is the last block allocated from the bottom of the free 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. 129</p> 130 131<CENTER><IMG SRC="./fig3-4.gif"><BR>Figure 3-4 Changing the Size of Frame Heap Memory Blocks<BR></CENTER> 132Use this function to change memory block size. 133<TABLE border="1"><CAPTION>Function for Changing the Size of Memory Blocks</CAPTION> 134<TR><TD>Functions</TD><TD>Functions</TD></TR> 135<TR><TD><A HREF="./FrmHeap/MEMResizeForMBlockFrmHeap.html"><CODE>MEMResizeForMBlockFrmHeap</CODE></A></TD><TD>Expands or reduces memory blocks. Returns the changed memory block size.</TD></TR> 136</TABLE> 137 138<p> 139If the free region size is smaller than the specified size when expanding a memory block, the <A HREF="./FrmHeap/MEMResizeForMBlockFrmHeap.html"><CODE>MEMResizeForMBlockFrmHeap</CODE></A> function fails and returns zero. 140</p> 141 142<H2>Getting the Allocatable Size</H2> 143<p> 144The Frame Heap Manager can find the size of the largest allocatable memory block. These functions are shown in the following table. 145</p> 146 147<TABLE border="1"><CAPTION>Functions for Getting the Allocatable Size</CAPTION> 148<TR><TD>Functions</TD><TD>Functions</TD></TR> 149<TR><TD><A HREF="./FrmHeap/MEMGetAllocatableSizeForFrmHeap.html"><CODE>MEMGetAllocatableSizeForFrmHeap</CODE></A></TD><TD>Gets the maximum size of the allocatable memory block. Alignment is fixed to four.</TD></TR> 150<TR><TD><A HREF="./FrmHeap/MEMGetAllocatableSizeForFrmHeapEx.html"><CODE>MEMGetAllocatableSizeForFrmHeapEx</CODE></A></TD><TD>Gets the maximum size of the allocatable memory block. Alignment can be specified.</TD></TR> 151</TABLE> 152 153<H2>Revision History</H2> 154<p> 1552006/03/01 Initial version. <BR>2006/06/27 Corrected an omission.<br> 156</p> 157<hr> 158<P>CONFIDENTIAL</p> 159</BODY> 160</HTML> 161
