(ntifs.h) RtlAllocateHeap 函式
RtlAllocateHeap 例程會從堆積配置記憶體區塊。
語法
NTSYSAPI PVOID RtlAllocateHeap(
[in] PVOID HeapHandle,
[in, optional] ULONG Flags,
[in] SIZE_T Size
);
參數
[in] HeapHandle
將配置記憶體的私人堆積句柄。 此參數是從 成功呼叫 RtlCreateHeap 傳回的句柄。
[in, optional] Flags
堆積配置的可控制層面。 指定上述任何值將會覆寫使用 RtlCreateHeap 建立堆積時所指定的對應值。 此參數可以是下列一或多個值。
| 旗標 | 意義 |
|---|---|
| HEAP_GENERATE_EXCEPTIONS | 系統會引發例外狀況來指出函式失敗，例如記憶體不足狀況，而不是傳回 NULL。 |
| HEAP_NO_SERIALIZE | 當 RtlAllocateHeap 正在存取堆積時，將不會使用互斥。 |
| HEAP_ZERO_MEMORY | 配置的記憶體將會初始化為零。 否則，記憶體不會初始化為零。 |
[in] Size
要配置的位元元組數目。 如果 HeapHandle 參數指定的堆積是不可成長的堆積， 則 Size 必須小於或等於堆積的虛擬記憶體閾值。 (如需詳細資訊，請參閱 Parameters 參數的 VirtualMemoryThreshold 成員至 RtlCreateHeap.)
傳回值
如果 呼叫 RtlAllocateHeap 成功，則傳回值會是新配置的區塊指標。 如果配置失敗，則傳回值為NULL。
備註
RtlAllocateHeap 會從指定的堆積配置指定大小的記憶體區塊。
若要釋放 由 RtlAllocateHeap 配置的記憶體區塊，請呼叫 RtlFreeHeap。
RtlAllocateHeap 配置的記憶體無法移動。 由於記憶體無法移動，因此堆積可能會變成分散。
當兩個或多個線程嘗試同時配置或釋放相同堆積中的區塊時，串行化可確保互斥。 串行化有一小部分的效能成本，但每當多個線程配置和釋放來自相同堆積的記憶體時，都必須使用它。 設定HEAP_NO_SERIALIZE值可排除堆積上的相互排除。 如果沒有串行化，使用相同堆積句柄的兩個或多個線程可能會嘗試同時配置或釋放記憶體，而可能導致堆積損毀。 因此，HEAP_NO_SERIALIZE值只能在下列情況下安全地使用：
進程只有一個線程。
進程有多個線程，但只有一個線程會呼叫特定堆積的堆積函式。
進程有多個線程，而且應用程式會提供自己的機制，以排除特定堆積。
注意
若要防範存取違規，請使用結構化例外狀況處理來保護寫入或讀取堆積的任何程序代碼。 如需使用記憶體存取進行結構化例外狀況處理的詳細資訊，請參閱 處理例外狀況。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP |
| 目標平台 | Universal |
| 標頭 | ntifs.h (包含 Ntifs.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL |