HeapCreate

HeapCreate creates a heap object that can be used by the calling process. The function reserves a contiguous block in the virtual address space of the process and allocates physical storage for a specified initial portion of this block.

Syntax

Copy

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

Parameters

flOptions

The optional attributes for the new heap. These flags will affect subsequent access to the new heap through calls to the heap functions (HeapAlloc, HeapFree, HeapReAlloc, and HeapSize).

You can specify one or more of the following flags:

Value	Description
HEAP_GENERATE_EXCEPTIONS	Specifies that the system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used when the heap functions allocate and free memory from this heap. The default, occurring when the HEAP_NO_SERIALIZE flag is not specified, is to serialize access to the heap. Serialization of heap access allows two or more threads to simultaneously allocate and free memory from the same heap.

dwInitialSize (ignored by eRTOS)

The initial size, in bytes, of the heap. This value determines the initial amount of physical storage that is allocated for the heap. The value is rounded up to the next page boundary.

dwMaximumSize

If MaximumSize is a non-zero value, it specifies the maximum size, in bytes, of the heap. HeapCreate rounds dwMaximumSize up to the next page boundary, and then reserves a block of that size in the process's virtual address space for the heap. If allocation requests made by HeapAlloc or HeapReAlloc exceed the initial amount of physical storage specified by dwInitialSize, the system allocates additional pages of physical storage for the heap, up to the heap's maximum size.

If dwMaximumSize is non-zero, the heap cannot grow, and an absolute limitation arises: the maximum size of a memory block in the heap is a bit less than 0x7FFF8 bytes. Requests to allocate larger blocks will fail, even if the maximum size of the heap is large enough to contain the block.

If dwMaximumSize is zero, it specifies that the heap can grow. The heap's size is limited only by available memory. Requests to allocate blocks larger than 0x7FFF8 bytes do not automatically fail; the system calls VirtualAlloc to obtain the memory needed for such large blocks. Applications that need to allocate large memory blocks should set dwMaximumSize to zero.

Return Value

If the function succeeds, it returns a handle to the newly created heap. If the function fails, it returns NULL.

To get extended error information, call GetLastError.

Remarks

HeapCreate creates a private heap object from which the calling process can allocate memory blocks by using HeapAlloc. The initial size determines the number of committed pages that are initially allocated for the heap. The maximum size determines the total number of reserved pages. These pages create a contiguous block in the process's virtual address space into which the heap can grow. If requests by HeapAlloc exceed the current size of committed pages, additional pages are automatically committed from this reserved space, assuming that the physical storage is available.

The memory of a private heap object is accessible only to the process that created it. If a dynamic-link library (RTDLL) creates a private heap, the heap is created in the address space of the process that called the RTDLL, and it is accessible only to that process.

The system uses memory from the private heap to store heap support structures, so not all of the specified heap size is available to the process. For example, if HeapAlloc requests 64 Kilobytes (K) from a heap with a maximum size of 64K, the request may fail because of system overhead.

If the HEAP_NO_SERIALIZE flag is not specified (the simple default), the heap will serialize access within the calling process. Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap.

Setting the HEAP_NO_SERIALIZE flag eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE flag can, therefore, be safely used only in the following situations:

The process has only one thread.
The process has multiple threads, but only one thread calls the heap functions for a specific heap.
The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

Requirements

Minimum supported version	Header	Library
eRTOS 1.0 SDK	windows.h	rtkrnl.lib