HeapCompact 函数 (heapapi.h)

项目
02/07/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 应用]
目标平台	Windows
标头	heapapi.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll