heapAlloc 函式 (heapapi.h)

發行項
02/26/2024

從堆積配置記憶體區塊。配置的記憶體無法移動。

語法

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	配置的記憶體將會初始化為零。否則，記憶體不會初始化為零。

值

意義

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。

例外狀況代碼	Description
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)
程式庫	Kernel32.lib
DLL	Kernel32.dll