HeapAlloc (Windows Embedded CE 6.0)

1/6/2010

This function allocates a block of unmovable memory from a heap.

Syntax

LPVOID HeapAlloc(
  HANDLE hHeap,
  DWORD dwFlags,
  DWORD dwBytes
);

Parameters

• hHeap
  [in] Handle to the heap from which the memory will be allocated.

  This parameter is a handle returned by the HeapCreate or GetProcessHeap function.

• dwFlags
  [in] Heap allocation options. Specifying any of these flags overrides the corresponding flag that was specified when the heap was created with HeapCreate.

  You can specify one or more of the following flags.

  Value	Description
  HEAP_NO_SERIALIZE	Ignored. The heap is always serialized.
  HEAP_ZERO_MEMORY	Initializes the allocated memory to zero. Otherwise, the memory is not initialized to zero.

• dwBytes
  [in] Number of bytes to be allocated.

  If the heap specified by the hHeap parameter is a non-growable heap, dwBytes must be less than 0x7FFF8.

  You create a non-growable heap by calling the HeapCreate function with a nonzero value.

Return Value

A pointer to the allocated memory block indicates success. Pointers returned by HeapAlloc and HeapReAlloc are valid pointers until they are freed by HeapFree.

NULL indicates failure. To get extended error information, call the GetLastError function. The following table shows possible return values for GetLastError.

Remarks

If HeapAlloc succeeds, it allocates at least the amount of memory requested; because heap allocation rounds the size of a memory block up to the next 32-byte boundary, the allocated size may be larger than the requested size. If the amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual size of the allocated block, use the HeapSize function.

To free a block of memory allocated by HeapAlloc, use the HeapFree function.

Memory allocated by HeapAlloc is not movable. Because the memory is not movable, the heap can become fragmented.

Heap memory management functions use a critical section to serialize access to a heap. Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. Serialization imposes a small performance cost, but serialization must be used whenever multiple threads allocate and free memory from the same heap.

When one thread enters the critical section to allocate or free blocks from the heap, any other threads attempting to enter the same critical section are blocked until the first thread releases the critical section. When a thread attempts to enter a critical section that is not owned by another thread, there is no contention, and therefore the thread incurs very little overhead in completing the heap operation.

Requirements

See Also

Reference

Memory Management Functions
GetProcessHeap
HeapCreate
HeapDestroy
HeapFree
HeapReAlloc
HeapSize