HeapCreate Function (Memory) - Windows API Reference

Syntax

HANDLE HeapCreate( DWORD flOptions, SIZE_T dwInitialSize, SIZE_T dwMaximumSize );

Parameters

flOptions [in]

Heap options. This parameter can be zero or one or more of the following values:

HEAP_NO_SERIALIZE: The heap is not protected by a critical section, so at least one other thread in the process must not be able to access the heap.
HEAP_CREATE_MARKER_FLAGS_INTERNAL: Reserved for system use.

dwInitialSize [in]

The initial size of the heap, in bytes. If this parameter is 0, the initial size is set to the system default. The system default is approximately 4 MB.

dwMaximumSize [in]

The maximum size of the heap, in bytes. If this parameter is 0, the maximum size is unbounded. For performance reasons, you should specify a reasonable maximum size for the heap. If you specify 0, the heap can grow until the system has no memory available.

Return Value

If the function succeeds, the return value is a handle to the newly created heap. The handle is a unique value used to identify the heap. If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The HeapCreate function creates a private heap object that can be accessed only by the calling process. The system reserves a contiguous virtual address range for the heap. The actual physical storage is allocated as needed when the application calls allocation functions such as HeapAlloc.

The heap handle returned by HeapCreate is used in subsequent calls to heap functions to manage the heap.

If flOptions is 0, the heap is created with default serialisation. This means that the system automatically protects the heap with a critical section, so that only one thread can access the heap at a time. If you set flOptions to HEAP_NO_SERIALIZE, you are responsible for ensuring that no more than one thread accesses the heap simultaneously.

To destroy the heap created by HeapCreate, call the HeapDestroy function.

Example

The following example creates a heap with default options, an initial size of 1MB, and an unbounded maximum size.


#include <windows.h>
#include <stdio.h>

int main() {
    HANDLE hHeap = NULL;

    // Create a heap with initial size 1MB and no maximum size limit
    hHeap = HeapCreate(0, 1024 * 1024, 0); // 1MB initial, unbounded max

    if (hHeap != NULL) {
        printf("Heap created successfully. Handle: %p\n", hHeap);

        // Example: Allocate memory from the heap
        LPVOID pData = HeapAlloc(hHeap, 0, 100); // Allocate 100 bytes
        if (pData != NULL) {
            printf("Memory allocated successfully: %p\n", pData);
            // ... use the allocated memory ...
            HeapFree(hHeap, 0, pData); // Free the allocated memory
            printf("Memory freed.\n");
        } else {
            fprintf(stderr, "HeapAlloc failed with error: %lu\n", GetLastError());
        }

        // Destroy the heap when done
        if (HeapDestroy(hHeap)) {
            printf("Heap destroyed successfully.\n");
        } else {
            fprintf(stderr, "HeapDestroy failed with error: %lu\n", GetLastError());
        }
    } else {
        fprintf(stderr, "HeapCreate failed with error: %lu\n", GetLastError());
    }

    return 0;
}

Windows API Reference