HeapCreate

  • Article

This function creates a heap object that is private to the calling process. This reserves a contiguous block of the virtual address space of the process and allocates physical storage for a specified initial portion of this block.

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

Parameters

  • flOptions
    [in] Specifies 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). The following table shows the flag you can specify.

    Value Description
    HEAP_NO_SERIALIZE Specifies that mutual exclusion will not be used when the heap functions allocate and free memory from this heap. The default, 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.

    This flag is ignored.

  • dwInitialSize
    [in] Specifies 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. To determine the size of a page on the host computer, use the GetSystemInfo function.

  • dwMaximumSize
    [in] If dwMaximumSize is a nonzero 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 virtual address space of the process for the heap. If allocation requests made by HeapAlloc or HeapReAlloc exceed the initial amount of physical storage space specified by dwInitialSize, the system allocates additional pages of physical storage for the heap, up to the heap's maximum size.

    Also, if dwMaximumSize is nonzero, the heap cannot grow and an absolute limitation arises where all allocations are fulfilled within the specified heap unless there is not enough free space.

    If dwMaximumSize is zero, it specifies that the heap is able to grow and the heap's size is limited only by available memory. Requests to allocate blocks larger than 0x0018000 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 Values

A handle to the newly created heap indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The HeapCreate function creates a private heap object from which the calling process can allocate memory blocks using the HeapAlloc function. These pages create a block in the virtual address space of the process 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 (DLL) creates a private heap, the heap is created in the address space of the process that called the DLL 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 the HeapAlloc function requests 64 KB from a heap with a maximum size of 64 KB, the request may fail because of system overhead.

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. A critical section is always used to serialize access to an individual heap. There is a critical section per heap to protect access to each heap. An attempt to grab a critical section that is not owned is a fast path operation that incurs little overhead. This would be similar to using the HEAP_NO_SERIALIZE flag if only one thread was ever accessing a particular heap. If there is contention for the critical section and therefore the heap, a new thread request to allocate heap space will serialize.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Winbase.h.
Link Library: Coredll.lib.

See Also

GetSystemInfo | HeapAlloc | HeapDestroy | HeapFree | HeapReAlloc | HeapSize | VirtualAlloc

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.