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>Expanded Heap Manager</TITLE>
8<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css">
9</HEAD>
10<BODY>
11
12<H1>Expanded Heap Manager</H1>
13<p>
14The Expanded Heap Manager and the C standard library <CODE>malloc()</CODE> and <CODE>free()</CODE> functions allocate and free memory in a similar way. 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.
15</p>
16
17<H2>Creating Heaps</H2>
18<p>
19To use the Expanded Heap Manager, you must first create an expanded heap. The following functions create and destroy expanded heaps.
20</p>
21
22<TABLE border="1">
23<CAPTION>Functions to Create and Destroy Expanded Heaps</CAPTION>
24<TR><TD>Function</TD><TD>Description</TD></TR>
25<TR><TD><A HREF="./ExpHeap/MEMCreateExpHeap.html"><CODE>MEMCreateExpHeap</CODE></A></TD><TD>Creates the expanded heap.</TD></TR>
26<TR><TD><A HREF="./ExpHeap/MEMCreateExpHeapEx.html"><CODE>MEMCreateExpHeapEx</CODE></A></TD><TD>Creates the expanded heap. Heap options can be specified.</TD></TR>
27<TR><TD><A HREF="./ExpHeap/MEMDestroyExpHeap.html"><CODE>MEMDestroyExpHeap</CODE></A></TD><TD>Destroys the expanded heap.</TD></TR>
28</TABLE>
29
30<H2>Allocating Memory Blocks</H2>
31<H3>Allocating and Freeing Memory Blocks</H3>
32<p>
33The following functions allocate and free memory blocks.
34</p>
35
36<TABLE border="1">
37<CAPTION>Functions for Allocating and Freeing Memory Blocks</CAPTION>
38<TR><TD>Function</TD><TD>Description</TD></TR>
39<TR><TD><A HREF="./ExpHeap/MEMAllocFromExpHeap.html"><CODE>MEMAllocFromExpHeap</CODE></A></TD><TD>Allocates a memory block from the expanded heap.</TD></TR>
40<TR><TD><A HREF="./ExpHeap/MEMAllocFromExpHeapEx.html"><CODE>MEMAllocFromExpHeapEx</CODE></A></TD><TD>Allocates a memory block from the expanded heap. The alignment can be specified (described in the next section).</TD></TR>
41<TR><TD><A HREF="./ExpHeap/MEMFreeToExpHeap.html"><CODE>MEMFreeToExpHeap</CODE></A></TD><TD>Frees a memory block.</TD></TR>
42</TABLE>
43
44<H3>Allocating the Minimum Memory Block Size</H3>
45<p>
46The Expanded Heap Manager needs 16 bytes to use as a memory block management region. The minimum aligment of allocated memory blocks must be on a 4-byte boundary; therefore, even if a one-byte memory block is allocated, 20 bytes of memory are consumed.
47</p>
48
49<H3>Procedure for Allocating Memory Blocks</H3>
50<p>
51The Expanded Heap Manager has two modes that identify free regions for allocating memory blocks. You can switch between modes. These modes are described below.
52</p>
53
54<TABLE border="1">
55<CAPTION>Memory Block Allocation Modes</CAPTION>
56<TR><TD>Mode</TD><TD>Description</TD></TR>
57<TR><TD><CODE>FIRST</CODE> Mode</TD><TD>Allocates a memory block from the first free region that is at least the size of the memory block to allocate.</TD></TR>
58<TR><TD><CODE>NEAR</CODE> Mode</TD><TD>Searches for a free region nearest in size to the memory block to allocate, then allocates the memory block from this free region.</TD></TR>
59</TABLE>
60
61<CENTER>
62<IMG SRC="./fig2-1.gif"><BR> Figure 2-1 Procedure for Allocating Expanded Heap Memory Blocks<BR>
63</CENTER>
64
65<p>
66<CODE>FIRST</CODE> is the default mode. Unlike <CODE>FIRST</CODE>, <CODE>NEAR</CODE> allocates a free block nearest in size to the memory block to allocate. If an exact match isn't 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.
67</p>
68
69<TABLE border="1">
70<CAPTION>Functions for Setting and Getting Allocation Modes</CAPTION>
71<TR><TD>Function</TD><TD>Description</TD></TR>
72<TR><TD><A HREF="./ExpHeap/MEMSetAllocModeForExpHeap.html"><CODE>MEMSetAllocModeForExpHeap</CODE></A></TD><TD>Sets the allocation mode.</TD></TR>
73<TR><TD><A HREF="./ExpHeap/MEMGetAllocModeForExpHeap.html"><CODE>MEMGetAllocModeForExpHeap</CODE></A></TD><TD>Gets the current allocation mode.</TD></TR>
74</TABLE>
75
76<p>
77The following are the allocation mode types that different functions use.
78</p>
79
80<TABLE border="1">
81<CAPTION>Allocation Mode Types That Functions Use</CAPTION>
82<TR><TD>Mode</TD><TD>Value Specified by the Function</TD></TR>
83<TR><TD><CODE>FIRST</CODE> Mode</TD><TD><CODE>MEM_EXPHEAP_ALLOC_MODE_FIRST</CODE></TD></TR>
84<TR><TD><CODE>NEAR</CODE> Mode</TD><TD><CODE>MEM_EXPHEAP_ALLOC_MODE_NEAR</CODE></TD></TR>
85</TABLE>
86
87<H3>Allocating Memory Blocks from the Top of the Heap Region</H3>
88<p>
89Generally, 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&ndash;term memory blocks from the bottom of the heap region, and temporary memory blocks from the top 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 is divided in half.
90</p>
91
92<CENTER>
93<IMG SRC="./fig2-2.gif"><BR> Figure 2-2 Mechanism for Segmenting Memory Blocks<BR>
94</CENTER>
95
96<p>
97In contrast, if you temporarily load the compressed data into a memory block allocated from the top of the heap region, the free space is not divided.
98</p>
99
100<CENTER>
101<IMG SRC="./fig2-3.gif"><BR> Figure 2-3 Method for Segmenting Expanded Heap Memory Blocks<BR>
102</CENTER>
103
104<p>
105To allocate memory blocks from the top of the heap region, use the memory block allocation function <A HREF="./ExpHeap/MEMAllocFromExpHeapEx.html"><CODE>MEMAllocFromExpHeapEx</CODE></A> and pass a negative value to the alignment argument (described below).
106</p>
107
108<H2>Specifying Alignment</H2>
109<p>
110The Expanded Heap Manager specifies alignment during memory block allocation. In the <A HREF="./ExpHeap/MEMAllocFromExpHeapEx.html">MEMAllocFromExpHeapEx</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="./ExpHeap/MEMAllocFromExpHeap.html"><CODE>MEMAllocFromExpHeap</CODE></A> function doesn't specify an alignment; the alignment value is always 4.
111</p>
112
113<H2>Adjusting the Heap Region Size</H2>
114<p>
115The Expanded Heap Manager can reduce the heap region size to match the heap content. Use this functionality only if memory blocks aren't allocated from the top of the heap region. Also note that the free memory that is closer to the bottom than the already allocated memory blocks don't change and reduce in size.
116</p>
117<p>
118After 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.
119<p>
120
121<CENTER>
122<IMG SRC="./fig2-4.gif"><BR> Figure 2-4 Adjusting the Size of the Extended Heap<BR>
123</CENTER>
124
125<p>
126The following function reduces heap region size.
127</p>
128
129<TABLE border="1">
130<CAPTION>Function for Reducing the Size of the Heap Region</CAPTION>
131<TR><TD>Function</TD><TD>Description</TD></TR>
132<TR><TD><A HREF="./ExpHeap/MEMAdjustExpHeap.html"><CODE>MEMAdjustExpHeap</CODE></A></TD><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>
137If the available free space is sufficient, the Expanded Heap Manager can change the size of the allocated memory blocks without moving them. After the memory blocks are reduced to a size smaller than the original, the remaining regions are used as free regions. If the new memory blocks are larger than the original size, the memory blocks must be followed by sufficient free space. If free regions follow the memory blocks, this function merges the free regions with the memory block to increase the size of the memory block.
138</p>
139
140<CENTER>
141<IMG SRC="./fig2-5.gif"><BR> Figure 2-5 Changing the Size of Expanded Heap Memory Blocks<BR>
142</CENTER>
143
144<p>
145Use this function to change memory block size.
146</p>
147
148<TABLE border="1">
149<CAPTION>Function for Changing the Size of Memory Blocks</CAPTION>
150<TR><TD>Function</TD><TD>Description</TD></TR>
151<TR><TD><A HREF="./ExpHeap/MEMResizeForMBlockExpHeap.html"><CODE>MEMResizeForMBlockExpHeap</CODE></A></TD><TD>Expands or reduces memory blocks. Returns the changed memory block size.</TD></TR>
152</TABLE>
153
154<p>
155If the specified size is slightly different than the size of the current memory block after reduction, in some cases a free region can't be used. In such cases, the <A HREF="./ExpHeap/MEMResizeForMBlockExpHeap.html"><CODE>MEMResizeForMBlockExpHeap</CODE></A> function doesn't reduce the memory block size and returns the size of the current memory block. If you attempt to expand memory block size when there is either no free region directly after the memory block, or if it was not possible to achieve the required expansion after defragmenting the free space behind the current memory block, <A HREF="./ExpHeap/MEMResizeForMBlockExpHeap.html"><CODE>MEMResizeForMBlockExpHeap</CODE></A> fails and returns zero.
156</p>
157
158<H2>Acquiring Free Space</H2>
159<p>
160The Expanded Heap Manager can obtain the total free regions. It can also obtain the size of the largest allocatable memory block. Those specific functions are shown in the following table.
161</p>
162
163<TABLE border="1">
164<CAPTION>Functions for Acquiring Free Memory</CAPTION>
165<TR><TD>Function</TD><TD>Description</TD></TR>
166<TR><TD><A HREF="./ExpHeap/MEMGetTotalFreeSizeForExpHeap.html"><CODE>MEMGetTotalFreeSizeForExpHeap</CODE></A></TD><TD>Gets the total size of the free region in the expanded heap.</TD></TR>
167<TR><TD><A HREF="./ExpHeap/MEMGetAllocatableSizeForExpHeap.html"><CODE>MEMGetAllocatableSizeForExpHeap</CODE></A></TD><TD>Gets the maximum size of the allocatable memory block. Alignment is fixed to four.</TD></TR>
168<TR><TD><A HREF="./ExpHeap/MEMGetAllocatableSizeForExpHeapEx.html"><CODE>MEMGetAllocatableSizeForExpHeapEx</CODE></A></TD><TD>Gets the maximum size of the allocatable memory block. Alignment can be specified.</TD></TR>
169</TABLE>
170
171<H2>Group IDs</H2>
172<p>
173When the Expanded Heap Manager acquires memory blocks, group IDs from 0 through 255 are stored in the memory block management region. A froup 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.
174<p>
175<UL>
176<LI>Collectively free only memory blocks with a specific group ID.
177<LI>Check memory use for each group ID. By managing group IDs per use or user, seeing how memory is used is easier.
178</UL>
179
180<p>
181The following functions set and get group IDs.
182</p>
183
184<TABLE border="1">
185<CAPTION>Functions for Setting and Getting Group IDs</CAPTION>
186<TR><TD>Function</TD><TD>Description</TD></TR>
187<TR><TD><A HREF="./ExpHeap/MEMSetGroupIDForExpHeap.html"><CODE>MEMSetGroupIDForExpHeap</CODE></A></TD><TD>Sets the group ID of the expanded heap.</TD></TR>
188<TR><TD><A HREF="./ExpHeap/MEMGetGroupIDForExpHeap.html"><CODE>MEMGetGroupIDForExpHeap</CODE></A></TD><TD>Gets the group ID of the expanded heap.</TD></TR>
189</TABLE>
190
191<H2>Processes for Memory Blocks</H2>
192<p>
193The 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 unavailable in the Expanded Heap Manager. Below are some examples.
194<p>
195
196<UL>
197<LI>Call a function that simultaneously frees only allocated memory blocks for temporary use from the top of the heap region.
198<LI>Get the total memory block capacity for a specific group ID.
199</UL>
200
201<p>
202This function runs the following process.
203</p>
204
205<TABLE border="1">
206<TR><TD>Function</TD><TD>Description</TD></TR>
207<TR><TD><A HREF="./ExpHeap/MEMVisitAllocatedForExpHeap.html"><CODE>MEMVisitAllocatedForExpHeap</CODE></A></TD><TD>Calls a user specified function for each allocated memory block.</TD></TR>
208</TABLE>
209
210<H2>Getting Memory Block Information</H2>
211<p>
212The 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 These functions get memory block information.
213</p>
214
215<TABLE border="1">
216<CAPTION>Functions for Getting Memory Block Information</CAPTION>
217<TR><TD>Function</TD><TD>Description</TD></TR>
218<TR><TD><A HREF="./ExpHeap/MEMGetSizeForMBlockExpHeap.html"><CODE>MEMGetSizeForMBlockExpHeap</CODE></A></TD><TD>Gets the size of the memory block.</TD></TR>
219<TR><TD><A HREF="./ExpHeap/MEMGetGroupIDForMBlockExpHeap.html"><CODE>MEMGetGroupIDForMBlockExpHeap</CODE></A></TD><TD>Gets the group ID of the memory block.</TD></TR>
220<TR><TD><A HREF="./ExpHeap/MEMGetAllocDirForMBlockExpHeap.html"><CODE>MEMGetAllocDirForMBlockExpHeap</CODE></A></TD><TD>Gets the allocation direction of the memory block.</TD></TR>
221</TABLE>
222
223<H2>Checking Heaps and Memory Blocks</H2>
224<p>
225The 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.
226</p>
227
228<TABLE border="1">
229<CAPTION>Functions that Check Extended Heaps and Memory Blocks</CAPTION>
230<TR><TD>Function</TD><TD>Description</TD></TR>
231<TR><TD><A HREF="./ExpHeap/MEMCheckExpHeap.html"><CODE>MEMCheckExpHeap</CODE></A></TD><TD>Checks whether the extended heap is destroyed.</TD></TR>
232<TR><TD><A HREF="./ExpHeap/MEMCheckForMBlockExpHeap.html"><CODE>MEMCheckForMBlockExpHeap</CODE></A></TD><TD>Checks whether the memory block is destroyed.</TD></TR>
233</TABLE>
234
235<H2>Revision History</H2>
236<P>2006/03/01 Initial version.</P>
237<hr>
238<P>CONFIDENTIAL</p>
239</BODY>
240</HTML>
241