heapReAlloc 函式 (heapapi.h)

  • 發行項

從堆積重新配置記憶體區塊。 此函式可讓您調整記憶體區塊的大小，並變更其他記憶體區塊屬性。 配置的記憶體無法移動。

語法

DECLSPEC_ALLOCATOR LPVOID HeapReAlloc(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem,
  [in] SIZE_T                 dwBytes
);

參數

[in] hHeap

要從中重新配置記憶體的堆積句柄。 這個句柄是由 HeapCreate 或 GetProcessHeap 函式所傳回。

[in] dwFlags

堆積重新配置選項。 指定值會覆寫使用 HeapCreate 函式建立堆積時 flOptions 參數中指定的對應值。 此參數可以是下列一或多個值。

值 意義
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_REALLOC_IN_PLACE_ONLY
0x00000010
 重新配置記憶體區塊時，不能有任何移動。 如果未指定此值，函式可能會將 區塊移至新的位置。 如果指定這個值，而且區塊在移動的情況下無法重設大小，則函式會失敗，讓原始記憶體區塊保持不變。
HEAP_ZERO_MEMORY
0x00000008
 如果重新配置要求的大小較大，則會將超過原始大小的記憶體額外區域初始化為零。 記憶體區塊的內容上限為原始大小，不會受到影響。

[in] lpMem

函式重新配置之內存區塊的指標。 這個指標是由先前呼叫 HeapAlloc 或 HeapReAlloc 函式所傳回。

[in] dwBytes

記憶體區塊的新大小，以位元組為單位。 記憶體區塊的大小可以使用這個函式來增加或減少。

如果 hHeap 參數指定的堆積是「不可成長」堆積， dwBytes 必須小於 0x7FFF8。 您可以呼叫具有非零值的 HeapCreate 函式，以建立不可成長的堆積。

傳回值

如果函式成功，傳回值會是重新配置記憶體區塊的指標。

如果函式失敗，而且您尚未指定 HEAP_GENERATE_EXCEPTIONS，則傳回值為 NULL。

如果函式失敗，而且您已指定 HEAP_GENERATE_EXCEPTIONS，此函式可能會產生下表所列的其中一個例外狀況。 如需詳細資訊，請參閱 GetExceptionCode。

例外狀況代碼 Description
STATUS_NO_MEMORY 配置嘗試失敗，因為缺少可用的記憶體或堆積損毀。
STATUS_ACCESS_VIOLATION 配置嘗試失敗，因為堆積損毀或函式參數不正確。

HeapReAlloc 所傳回的記憶體對齊方式在 WinNT.h 中MEMORY_ALLOCATION_ALIGNMENT：

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

如果函式失敗，它不會呼叫 SetLastError。 應用程式無法呼叫 GetLastError 以取得擴充的錯誤資訊。

備註

如果 HeapReAlloc 成功，則至少配置所要求的記憶體數量。

如果 HeapReAlloc 失敗，則不會釋放原始記憶體，而且原始句柄和指標仍然有效。

HeapReAlloc 保證會保留要重新配置的記憶體內容，即使新記憶體配置在不同的位置也一樣。 保留記憶體內容的程式牽涉到可能非常耗時的記憶體複製作業。

若要釋放 HeapReAlloc 所配置的記憶體區塊，請使用 HeapFree 函式。

當兩個或多個線程嘗試同時配置或釋放相同堆積中的區塊時，串行化可確保互斥。 串行化有一小部分的效能成本，但每當多個線程配置和釋放來自相同堆積的記憶體時，都必須使用它。 設定 HEAP_NO_SERIALIZE 值可排除堆積上的相互排除。 如果沒有串行化，使用相同堆積句柄的兩個或多個線程可能會嘗試同時配置或釋放記憶體，而可能導致堆積損毀。 因此， HEAP_NO_SERIALIZE 值只能在下列情況下安全地使用：

  • 進程只有一個線程。
  • 進程有多個線程，但只有一個線程會呼叫特定堆積的堆積函式。
  • 進程有多個線程，而且應用程式會提供自己的機制，以排除特定堆積。

規格需求

需求 值
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 heapapi.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

堆積函式

HeapAlloc

HeapFree

記憶體管理功能

VBS 記憶體保護區中可用的 Vertdll API