HeapCreate (Windows Embedded CE 6.0)

1/6/2010

This function reserves memory from the shared memory area. Then use HeapAlloc to allocate memory from the reserved memory.

Syntax

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

Parameters

• flOptions
  [in] Optional attributes for the new heap.

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

  The following table shows possible values.

  Value	Description
  HEAP_NO_SERIALIZE	This flag is ignored.
  HEAP_SHARED_READONLY	Specifies that heaps created with this flag will be readable by other processes and only writeable by the process that created the heap. Note: Running in kernel mode is required in order to create or use a heap with the HEAP_SHARED_READONLY flag, and this shared heap protection only applies to threads that are not in kernel mode. If the caller is not trusted, the call fails with the error code ERROR_ACCESS_DENIED.

• dwInitialSize
  [in] 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.

  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 can 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 Value

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 size of committed pages, additional pages are committed from this reserved space, assuming that the physical storage is available.

All kernel mode threads can write to the heap, and all other threads can read from the heap.** For Windows Embedded CE, if you want to use shared heaps as if they are regular heaps, your applications must be trusted*.* Shared heap memory resides in the shared memory area, so any module can read the shared heap memory. Rather than creating shared heap memory, a preferable approach to sharing writeable memory between processes is to implement a simple heap manager, and use it with a named memory mapped file. For more information about memory mapped files, see File Mapping Functions.

You can also use CeHeapCreate, which allows you to use a custom memory allocation function. The memory allocation function can reserve memory by calling CreateFileMapping on a memory mapped file that does not have an underlying file, and then map a view of the entire mapping. The function to commit memory can do nothing, or it can read the physical pages underneath so they are paged in. The free function then does nothing when decommitting memory, and then when releasing memory, the free function closes the memory mapping. To share this memory between processes, set up a single process to allocate and free memory from the heap. All processes that share this memory call into this process. The process that manages the heap memory uses the named memory mapped file as a heap, and the other processes open the memory mapped file by its name, and then obtain a pointer to the memory from the process that manages the heap memory. To access the shared memory, processes should open a mapping and a view.

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 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 might 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, but it must be used when 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 is 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

Header	winbase.h
Library	coredll.lib
Windows Embedded CE	Windows CE 1.0 and later

See Also

Reference

Memory Management Functions
GetSystemInfo
HeapAlloc
HeapCreate
HeapDestroy
HeapFree
HeapReAlloc
HeapSize
VirtualAlloc

Other Resources

File Mapping Functions
Modified Kernel APIs
CeVirtualSharedAlloc
CreateFileMapping