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

Статья
02/02/2024

Освобождает блок памяти, выделенный из кучи функцией HeapAlloc или HeapReAlloc .

Синтаксис

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

Параметры

[in] hHeap

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

[in] dwFlags

Параметры бесплатной кучи. При указании следующего значения переопределяется соответствующее значение, указанное в параметре flOptions при создании кучи с помощью функции HeapCreate .

Значение	Значение
HEAP_NO_SERIALIZE 0x00000001	Сериализованный доступ не будет использоваться. Дополнительные сведения см. в подразделе "Примечания". Чтобы убедиться, что сериализованный доступ отключен для всех вызовов этой функции, укажите HEAP_NO_SERIALIZE в вызове HeapCreate. В этом случае необязательно дополнительно указывать HEAP_NO_SERIALIZE в вызове функции. Не указывайте это значение при доступе к куче процесса. Система может создавать дополнительные потоки в процессе приложения, такие как обработчик CTRL+C, которые одновременно обращаются к куче процесса.

Значение

HEAP_NO_SERIALIZE
0x00000001

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

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