HeapCompact 函式（heapapi.h）

發行項
08/15/2024

傳回指定堆積中最大認可可用區塊的大小。如果已設定 [在免費全域旗標上停用堆積聯合，此函式也會聯合堆積中相鄰的可用記憶體區塊。

語法

SIZE_T HeapCompact(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags
);

參數

[in] hHeap

堆積的句柄。 HeapCreate 或 GetProcessHeap 函式會傳回此句柄。

[in] dwFlags

堆積存取選項。此參數可以是下列值。

價值	意義
HEAP_NO_SERIALIZE 0x00000001	不會使用串行化存取。如需詳細資訊，請參閱。若要確保所有對這個函式的呼叫停用串行化存取，請在呼叫 heapCreate中指定 HEAP_NO_SERIALIZE。在此情況下，不需要在此函數調用中另外指定 HEAP_NO_SERIALIZE。存取進程堆積時，請勿指定此值。系統可能會在應用程式的進程內建立其他線程，例如 CTRL+C 處理程式，以同時存取進程堆積。

價值

意義

HEAP_NO_SERIALIZE
0x00000001

不會使用串行化存取。

如需詳細資訊，請參閱。

若要確保所有對這個函式的呼叫停用串行化存取，請在呼叫 heapCreate中指定 HEAP_NO_SERIALIZE。在此情況下，不需要在此函數調用中另外指定 HEAP_NO_SERIALIZE。

存取進程堆積時，請勿指定此值。系統可能會在應用程式的進程內建立其他線程，例如 CTRL+C 處理程式，以同時存取進程堆積。

傳回值

如果函式成功，傳回值是堆積中最大認可可用區塊的大小，以位元組為單位。

如果函式失敗，傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

在不太可能的情況下，堆積中絕對沒有可用的空間，函式傳回值為零，而且 GetLastError 傳回值NO_ERROR。

言論

HeapCompact 函式主要用於偵錯。一般而言，每當呼叫 HeapFree 函式時，系統會壓縮堆積，而且 HeapCompact 函式會傳回堆積中最大可用區塊的大小，但不會進一步壓縮堆積。如果在偵錯期間設定免費全域旗標的停用堆積，系統就不會壓縮堆積，而且呼叫 HeapCompact 函式會壓縮堆積。如需全域旗標的詳細資訊，請參閱 GFlags 檔。

不保證應用程式可以成功配置 HeapCompact所傳回大小的記憶體區塊。其他線程或認可臨界值可能會防止這類配置。

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

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

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	heapapi.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll