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 class="api_list" border="1"> 23<CAPTION>Functions for Creating and Destroying Heaps</CAPTION> 24<TR><TD><B>Functions</B></TD><TD><B>Features</B></TD></TR> 25<TR><TH><A HREF="./FrmHeap/MEMCreateFrmHeap.html">MEMCreateFrmHeap</A></TH><TD>Creates the frame heap.</TD></TR> 26<TR><TH><A HREF="./FrmHeap/MEMCreateFrmHeapEx.html">MEMCreateFrmHeapEx</A></TH><TD>Creates the frame heap. Heap options can be specified.</TD></TR> 27<TR><TH><A HREF="./FrmHeap/MEMDestroyFrmHeap.html">MEMDestroyFrmHeap</A></TH><TD>Destroys the frame heap.</TD></TR> 28</TABLE> 29 30<H2>Allocating Memory Blocks</H2> 31<H3>Allocating and Freeing Memory Blocks</H3> 32<p> 33The 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. 34</p> 35 36<CENTER><IMG SRC="./fig3-1.gif"><BR> <B>Figure 3-1 Allocating Memory for the Frame Heap</B><BR></CENTER> 37 38<p> 39The following functions alblocate memory blocks. 40</p> 41 42<TABLE class="api_list" border="1"> 43<CAPTION>Functions for Allocating Memory Blocks</CAPTION> 44<TR><TD><B>Functions</B></TD><TD><B>Features</B></TD></TR> 45<TR><TH><A HREF="./FrmHeap/MEMAllocFromFrmHeap.html">MEMAllocFromFrmHeap</A></TH><TD>Allocates a memory block from frame heap.</TD></TR> 46<TR><TH><A HREF="./FrmHeap/MEMAllocFromFrmHeapEx.html">MEMAllocFromFrmHeapEx</A></TH><TD>Allocates a memory block from frame heap. The alignment can be specified (described in the next section).</TD></TR> 47</TABLE> 48 49<p> 50To allocate memory blocks from the end of the heap region, pass a negative value to the alignment argument in the <A HREF="./FrmHeap/MEMAllocFromFrmHeapEx.html"><CODE>MEMAllocFromFrmHeapEx</CODE></A> function. 51</p> 52 53<H3>Allocating the Minimum Memory Block Size</H3> 54<p> 55Even 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. 56</p> 57 58<H2>Specifying Alignment</H2> 59<p> 60The 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 rear 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. 61</p> 62 63<H2>Freeing Memory Blocks</H2> 64<p> 65Because 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. 66</p> 67 68<TABLE class="api_list" border="1"> 69<CAPTION>Methods for Freeing Memory Blocks</CAPTION> 70<TR><TD><B>Method</B></TD><TD><B>Content</B></TD></TR> 71<TR><TH>Deallocate from the front.</TH><TD>Frees memory block groups allocated from the bottom of the heap region.</TD></TR> 72<TR><TH>Deallocate from the rear.</TH><TD>Frees memory block groups allocated from the top of the heap region.</TD></TR> 73<TR><TH>Deallocate all.</TH><TD>Simultaneously frees all allocated memory blocks from the heap.</TD></TR> 74</TABLE> 75 76<p> 77The following function frees memory blocks. 78</p> 79 80<TABLE class="api_list" border="1"> 81<CAPTION>Function for Freeing Memory Blocks</CAPTION> 82<TR><TD><B>Functions</B></TD><TD><B>Features</B></TD></TR> 83<TR><TH><A HREF="./FrmHeap/MEMFreeToFrmHeap.html">MEMFreeToFrmHeap</A></TH><TD>Simultaneously frees memory blocks using the specified method.</TD></TR> 84</TABLE> 85 86<p> 87The following deallocation methods can be specified in the <A HREF="./FrmHeap/MEMFreeToFrmHeap.html"><CODE>MEMFreeToFrmHeap</CODE></A> function. 88</p> 89 90<TABLE class="api_list" border="1"> 91<CAPTION>Code Values to Specify in Functions for Freeing Memory Blocks</CAPTION> 92<TR><TD><B>Method</B></TD><TD><B>Value Specified in the Function</B></TD></TR> 93<TR><TH>Deallocate from the front.</TH><TD><CODE><CODE>MEM_FRMHEAP_FREE_HEAD</CODE></CODE></TD></TR> 94<TR><TH>Deallocate from the rear.</TH><TD><CODE><CODE>MEM_FRMHEAP_FREE_TAIL</CODE></CODE></TD></TR> 95<TR><TH>Deallocate all.</TH><TD><CODE>MEM_FRMHEAP_FREE_ALL</CODE> (This is equivalent to specifying both <CODE>MEM_FRMHEAP_FREE_HEAD</CODE> and <CODE>MEM_FRMHEAP_FREE_TAIL</CODE> simultaneously.))</TD></TR> 96</TABLE> 97 98<p> 99The 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. 100</p> 101 102<H2>Saving and Restoring Memory Block Allocation Status</H2> 103<p> 104The 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. 105</p> 106 107<CENTER><IMG SRC="./fig3-2.gif"><BR> <B>Figure 3-2 Mechanism for Saving and Restoring the Memory Block Allocation Status of a Frame Heap</B><BR></CENTER> 108 109<p> 110The following functions save and restore memory block allocation status. 111</p> 112 113<TABLE class="api_list" border="1"> 114<CAPTION>Functions for Saving and Restoring Memory Block Allocation Status</CAPTION> 115<TR><TD><B>Functions</B></TD><TD><B>Features</B></TD></TR> 116<TR><TH><A HREF="./FrmHeap/MEMRecordStateForFrmHeap.html">MEMRecordStateForFrmHeap</A></TH><TD>Saves the memory block allocation status.</TD></TR> 117<TR><TH><A HREF="./FrmHeap/MEMFreeByStateToFrmHeap.html">MEMFreeByStateToFrmHeap</A></TH><TD>Restores the memory block allocation status.</TD></TR> 118</TABLE> 119 120<H2>Adjusting the Heap Region Size</H2> 121<p> 122The 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. 123</p> 124 125<CENTER><IMG SRC="./fig3-3.gif"><BR> <B>Figure 3-3 Adjusting the Size of the Frame Heap</B><BR></CENTER> 126 127<P>The following function reduces heap region size.</P> 128 129<TABLE class="api_list" border="1"> 130<CAPTION>Function for Reducing the Size of the Heap Region</CAPTION> 131<TR><TD><B>Functions</B></TD><TD><B>Features</B></TD></TR> 132<TR><TH><A HREF="./FrmHeap/MEMAdjustFrmHeap.html">MEMAdjustFrmHeap</A></TH><TD>Reduces the size of the heap region by freeing unused regions at the top of the heap region.</TD></TR> 133</TABLE> 134 135<H2>Changing Memory Block Size</H2> 136<p> 137The 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. 138</p> 139 140<CENTER><IMG SRC="./fig3-4.gif"><BR> <B>Figure 3-4 Changing the Size of Frame Heap Memory Blocks</B><BR></CENTER> 141 142<P>Use this function to change memory block size.</P> 143 144<TABLE class="api_list" border="1"> 145<CAPTION>Function for Changing the Size of Memory Blocks</CAPTION> 146<TR><TD><B>Functions</B></TD><TD><B>Features</B></TD></TR> 147<TR><TH><A HREF="./FrmHeap/MEMResizeForMBlockFrmHeap.html">MEMResizeForMBlockFrmHeap</A></TH><TD>Expands or reduces memory blocks. Returns the changed memory block size.</TD></TR> 148</TABLE> 149 150<p> 151If the available 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. 152</p> 153 154<H2>Getting the Allocatable Size</H2> 155<p> 156The Frame Heap Manager can obtain the size of the largest allocatable memory block. These functions are shown in the following table. 157</p> 158 159<TABLE class="api_list" border="1"> 160<CAPTION>Functions for Getting the Allocatable Size</CAPTION> 161<TR><TD><B>Functions</B></TD><TD><B>Features</B></TD></TR> 162<TR><TH><A HREF="./FrmHeap/MEMGetAllocatableSizeForFrmHeap.html">MEMGetAllocatableSizeForFrmHeap</A></TH><TD>Gets the maximum size of the allocatable memory block. Alignment is fixed to four.</TD></TR> 163<TR><TH><A HREF="./FrmHeap/MEMGetAllocatableSizeForFrmHeapEx.html">MEMGetAllocatableSizeForFrmHeapEx</A></TH><TD>Gets the maximum size of the allocatable memory block. Alignment can be specified.</TD></TR> 164</TABLE> 165 166<H2>Revision History</H2> 167<p> 1682006/06/27 Corrected an omission.<br>2006/03/01 Initial version.<BR> 169</p> 170 171<hr><p>CONFIDENTIAL</p></body> 172</HTML> 173
