heapAlloc 函数 (heapapi.h)

  • 项目

从堆中分配内存块。 分配的内存不可移动。

语法

DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags,
  [in] SIZE_T dwBytes
);

参数

[in] hHeap

要从中分配内存的堆的句柄。 此句柄由 HeapCreate 或 GetProcessHeap 函数返回。

[in] dwFlags

堆分配选项。 指定这些值中的任何一个都将替代使用 HeapCreate 创建堆时指定的相应值。 此参数可使用以下一个或多个值。

值 含义
HEAP_GENERATE_EXCEPTIONS
0x00000004
 系统将引发异常以指示函数失败（例如内存不足情况），而不是返回 NULL。

若要确保为此函数的所有调用生成异常，请在调用 HeapCreate 时指定HEAP_GENERATE_EXCEPTIONS。 在这种情况下，无需在此函数调用中额外指定 HEAP_GENERATE_EXCEPTIONS 。
HEAP_NO_SERIALIZE
0x00000001
 序列化访问将不用于此分配。

有关详细信息，请参阅“备注”。

若要确保禁用对此函数的所有调用的序列化访问，请在调用 HeapCreate 中指定HEAP_NO_SERIALIZE。 在这种情况下，无需在此函数调用中额外指定 HEAP_NO_SERIALIZE 。

访问进程的默认堆时，不应指定此值。 系统可能会在应用程序的进程中创建其他线程，例如同时访问进程的默认堆的 CTRL+C 处理程序。
HEAP_ZERO_MEMORY
0x00000008
 分配的内存将初始化为零。 否则，内存不会初始化为零。

[in] dwBytes

要分配的字节数。

如果 hHeap 参数指定的堆是“不可增长的”堆， 则 dwBytes 必须小于 0x7FFF8。 可以通过使用非零值调用 HeapCreate 函数来创建不可增长的堆。

返回值

如果函数成功，则返回值是指向已分配内存块的指针。

如果函数失败并且您尚未指定 HEAP_GENERATE_EXCEPTIONS，则返回值为 NULL。

如果函数失败并且已指定 HEAP_GENERATE_EXCEPTIONS，则函数可能会生成下表中列出的任一异常。 特定例外取决于堆损坏的性质。 有关详细信息，请参阅 GetExceptionCode。

异常代码 说明
STATUS_NO_MEMORY 由于缺少可用内存或堆损坏，分配尝试失败。
STATUS_ACCESS_VIOLATION 由于堆损坏或函数参数不正确，分配尝试失败。

如果函数失败，则它不会调用 SetLastError。 应用程序无法调用 GetLastError 以获取扩展错误信息。

注解

如果 HeapAlloc 函数成功，它将分配至少请求的内存量。

若要从进程的默认堆分配内存，请将 HeapAlloc 与 GetProcessHeap 函数返回的句柄一起使用。

若要释放 HeapAlloc 分配的内存块，请使用 HeapFree 函数。

HeapAlloc 分配的内存不可移动。 HeapAlloc 返回的地址在释放或重新分配内存块之前有效;内存块不需要锁定。 由于系统无法压缩专用堆，因此它可能会碎片化。

HeapAlloc 返回的内存对齐方式在 WinNT.h 中MEMORY_ALLOCATION_ALIGNMENT：

#if defined(_WIN64) || defined(_M_ALPHA)
#define MEMORY_ALLOCATION_ALIGNMENT 16
#else
#define MEMORY_ALLOCATION_ALIGNMENT 8
#endif

以各种分配大小分配大量内存的应用程序可以使用 低碎片堆 来减少堆碎片。

当两个或多个线程尝试从同一堆同时分配或释放块时，序列化可确保相互排斥。 序列化的性能成本很小，但每当多个线程从同一个堆分配和释放内存时，必须使用它。 设置 HEAP_NO_SERIALIZE 值可消除堆上的相互排斥。 如果不进行序列化，使用同一堆句柄的两个或多个线程可能会尝试同时分配或释放内存，这可能会导致堆损坏。 因此，只能在以下情况下安全地使用 HEAP_NO_SERIALIZE 值：

  • 进程只有一个线程。
  • 进程有多个线程，但只有一个线程调用特定堆的堆函数。
  • 进程具有多个线程，应用程序提供自己的机制，用于对特定堆进行相互排斥。

示例

有关示例，请参阅 AWE 示例。

要求

要求 值
最低受支持的客户端 Windows XP [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2003 [桌面应用 | UWP 应用]
目标平台 Windows
标头 heapapi.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

堆函数

HeapFree

HeapReAlloc

内存管理函数

VBS enclave 中可用的 Vertdll API