heapFree 函式 (heapapi.h)

發行項
03/05/2024

釋放 HeapAlloc 或 HeapReAlloc 函式從堆積配置的記憶體區塊。

語法

BOOL HeapFree(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem
);

參數

[in] hHeap

要釋放其記憶體區塊之堆積的句柄。 HeapCreate 或 GetProcessHeap 函式會傳回此句柄。

[in] dwFlags

堆積可用選項。指定下列值會覆寫使用 HeapCreate 函式建立堆積時，flOptions 參數中指定的對應值。

值	意義
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 處理程式，以同時存取進程堆積。

[in] lpMem

要釋放之內存區塊的指標。 HeapAlloc 或 HeapReAlloc 函式會傳回此指標。此指標可以是 NULL。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。應用程式可以呼叫 GetLastError 以取得擴充錯誤資訊。

備註

您不應該以任何方式參考 HeapFree 釋放的記憶體。釋放該記憶體之後，任何可能已在其中的資訊一直消失。如果您需要資訊，請勿釋放包含資訊的記憶體。函式呼叫會傳回記憶體 (的相關信息，例如 HeapSize) 可能無法與釋放的記憶體搭配使用，因為它們可能會傳回假的數據。使用相同的指標呼叫 HeapFree 兩次可能會導致堆積損毀，導致後續呼叫 HeapAlloc 傳回相同的指標兩次。

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

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

範例

如需範例，請參閱取得進程堆積。

規格需求

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