heapSize 函式 (heapapi.h)

  • 發行項

擷取 HeapAlloc 或 HeapReAlloc 函式從堆積配置的記憶體區塊大小。

語法

SIZE_T HeapSize(
  [in] HANDLE  hHeap,
  [in] DWORD   dwFlags,
  [in] LPCVOID lpMem
);

參數

[in] hHeap

記憶體區塊所在的堆積句柄。 HeapCreate 或 GetProcessHeap 函式會傳回此句柄。

[in] dwFlags

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

值 意義
HEAP_NO_SERIALIZE
0x00000001
 將不會使用串行化存取。 如需詳細資訊，請參閱＜備註＞。

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

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

[in] lpMem

記憶體區塊的指標，其函式將取得其大小。 這是 HeapAlloc 或 HeapReAlloc 函式所傳回的指標。 記憶體區塊必須來自 hHeap 參數所指定的堆積。

傳回值

如果函式成功，則傳回值是所配置記憶體區塊的要求大小，以位元組為單位。

如果函式失敗，則傳回值為 (SIZE_T)-1。 函式不會呼叫 SetLastError。 應用程式無法呼叫 GetLastError 以取得擴充錯誤資訊。

如果 lpMem 參數參考的堆積配置不在 hHeap 參數所指定的堆積中， HeapSize 函式的行為是未定義的。

備註

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

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

規格需求

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

另請參閱

堆積函式

HeapAlloc

HeapReAlloc

記憶體管理功能

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