Функция HeapCompact (heapapi.h)

  • Статья

Возвращает размер наибольшего зафиксированного свободного блока в указанной куче. Если установлен флаг Отключить объединение кучи на свободном глобальном уровне, эта функция также объединяет соседние свободные блоки памяти в куче.

Синтаксис

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

Параметры

[in] hHeap

Дескриптор кучи. Этот дескриптор возвращается функцией HeapCreate или GetProcessHeap .

[in] dwFlags

Параметры доступа к куче. Этот параметр может иметь следующее значение.

Значение Значение
HEAP_NO_SERIALIZE
0x00000001
 Сериализованный доступ не будет использоваться.

Дополнительные сведения см. в подразделе "Примечания".

Чтобы убедиться, что сериализованный доступ отключен для всех вызовов этой функции, укажите HEAP_NO_SERIALIZE в вызове HeapCreate. В этом случае необязательно дополнительно указывать 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
Header heapapi.h (включая Windows.h)
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также

Функции кучи

HeapCreate

HeapValidate

Функции управления памятью

API-интерфейсы Vertdll, доступные в анклавах VBS