heapAlloc 函数 (heapapi.h)
从堆中分配内存块。 分配的内存不可移动。
语法
DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
[in] HANDLE hHeap,
[in] DWORD dwFlags,
[in] SIZE_T dwBytes
);
参数
[in] hHeap
要从中分配内存的堆的句柄。 此句柄由 HeapCreate 或 GetProcessHeap 函数返回。
[in] dwFlags
堆分配选项。 指定这些值中的任何一个都将替代使用 HeapCreate 创建堆时指定的相应值。 此参数可使用以下一个或多个值。
| 值 | 含义 |
|---|---|
|
系统将引发异常以指示函数失败（例如内存不足情况），而不是返回 NULL。
若要确保为此函数的所有调用生成异常，请在调用 HeapCreate 时指定HEAP_GENERATE_EXCEPTIONS。 在这种情况下，无需在此函数调用中额外指定 HEAP_GENERATE_EXCEPTIONS 。 |
|
序列化访问将不用于此分配。
有关详细信息，请参阅“备注”。 若要确保禁用对此函数的所有调用的序列化访问，请在调用 HeapCreate 中指定HEAP_NO_SERIALIZE。 在这种情况下，无需在此函数调用中额外指定 HEAP_NO_SERIALIZE 。 访问进程的默认堆时，不应指定此值。 系统可能会在应用程序的进程中创建其他线程，例如同时访问进程的默认堆的 CTRL+C 处理程序。 |
|
分配的内存将初始化为零。 否则，内存不会初始化为零。 |
[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 |