Using a Separate Heap

Instead of adding more size to the local heap, you might need to create a series of separate heaps. For example, a word processor might have a separate heap associated with each text file. Because you can delete separate heaps, fragmentation is not as much of an issue.

    To allocate and deallocate memory on a separate heap

1. Call the HeapCreate function.

   HeapCreate returns a handle. Use this handle to reference which heap you are using in the following steps.

2. Call HeapAlloc to allocate memory from the heap to your application.

   Windows CE does not place any limits on the size of a separate heap. As long as you have virtual and physical memory addresses available, you can allocate memory from the separate heap.

3. Use the memory that is allocated to your application.
4. If necessary, call HeapSize and HeapReAlloc to reallocate the separate heap memory.

   If you need to increase the size of a block, call HeapSize to determine if the block contains enough space. Then, call HeapReAlloc to either add memory to the top of the allocation or to move the block to a larger area.

5. Once you are done, call the HeapFree function to deallocate the memory back to Windows CE.

   Like the local heap, Windows CE deallocates a page only if all of the blocks within that page are also deallocated. This may result in fragmentation within the separate heap.

6. Once you are done with the heap, call the HeapDestroy function to return all of the heap memory to Windows CE.

   You do not have to call HeapFree on all blocks within the separate heap before you call HeapDestroy.

The following code example shows how to create a new heap.

LPBYTE pbMyPointer = NULL;
HANDLE hMyNewHeap = NULL;
LPVOID lpHeapMemory = NULL;
LPVOID lpHeapMem2 = NULL;
UINT uiSize;
BOOL bResult;

hMyNewHeap = HeapCreate (0,     // *do* serialize
                         35000, // 35,000 bytes wanted
                         0);    // Unsupported in Windows CE

The following code example shows how to allocate memory from the heap even when the heap is very small, by using HeapAlloc.

lpHeapMemory = HeapAlloc (hMyNewHeap,       // Specify which heap
                          HEAP_ZERO_MEMORY, // Zero the memory
                          42);              // Number of bytes
if (lpHeapMemory == NULL)
{
  // Your error-handling code goes here. You can use
  // the GetLastError function to obtain more information.
}

// The return value is actually the address of the memory.
pbMyPointer = (LPBYTE)lpHeapMemory;

// Your code to use the memory goes here.
// SomeFunctionCall (pbMyPointer, and so on)
// . . .

The following code example shows how to check the size of part of the heap by using HeapSize.

uiSize = HeapSize (hMyNewHeap,    // Specify the heap
                   0,             // No flags
                   lpHeapMemory); // Specify which memory
if (uiSize == 0)
{
  // Your error-handling code goes here. You can use
  // the GetLastError function to obtain more information.
}

The following code example shows how to change the size of part of the heap by using HeapReAlloc.

lpHeapMem2 = HeapReAlloc (hMyNewHeap,   // Specify which heap
                          0,            // Options (none)
                          lpHeapMemory, // Existing memory
                          100);         // New size, in bytes
if (lpHeapMem2 == NULL)
{
  // Your error-handling code goes here. You can use
  // the GetLastError function to obtain more information.
}

// The return value is actually the address of the memory.
pbMyPointer = (LPBYTE)lpHeapMem2;

The following code example shows how to free memory from the heap by using HeapFree.

bResult = HeapFree (hMyNewHeap,       // Specify which heap
                    0,                // Options (none)
                    lpHeapMem2);      // Specify what to free
if (!bResult)
{
  // Your error-handling code goes here. You can use
  // the GetLastError function to obtain more information.
}

// Always zero the caller's pointer after freeing memory.
lpHeapMem2 = NULL;

The following code example shows how to destroy the heap by using HeapDestroy.

bResult = HeapDestroy (hMyNewHeap);

if (!bResult)
{
  // Your error-handling code goes here. You can use
  // the GetLastError function to obtain more information.
}