Função HeapFree (heapapi.h)

Artigo
02/26/2024

Libera um bloco de memória alocado de um heap pela função HeapAlloc ou HeapReAlloc .

Sintaxe

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

Parâmetros

[in] hHeap

Um identificador para o heap cujo bloco de memória deve ser liberado. Esse identificador é retornado pela função HeapCreate ou GetProcessHeap .

[in] dwFlags

As opções livres de heap. Especificar o valor a seguir substitui o valor correspondente especificado no parâmetro flOptions quando o heap foi criado usando a função HeapCreate .

Valor	Significado
HEAP_NO_SERIALIZE 0x00000001	O acesso serializado não será usado. Para obter mais informações, consulte Comentários. Para garantir que o acesso serializado esteja desabilitado para todas as chamadas para essa função, especifique HEAP_NO_SERIALIZE na chamada para HeapCreate. Nesse caso, não é necessário especificar adicionalmente HEAP_NO_SERIALIZE nessa chamada de função. Não especifique esse valor ao acessar o heap de processo. O sistema pode criar threads adicionais dentro do processo do aplicativo, como um manipulador CTRL+C, que acessam simultaneamente o heap do processo.

Valor

Significado

HEAP_NO_SERIALIZE
0x00000001

O acesso serializado não será usado. Para obter mais informações, consulte Comentários.

Para garantir que o acesso serializado esteja desabilitado para todas as chamadas para essa função, especifique HEAP_NO_SERIALIZE na chamada para HeapCreate. Nesse caso, não é necessário especificar adicionalmente HEAP_NO_SERIALIZE nessa chamada de função.

Não especifique esse valor ao acessar o heap de processo. O sistema pode criar threads adicionais dentro do processo do aplicativo, como um manipulador CTRL+C, que acessam simultaneamente o heap do processo.

[in] lpMem

Um ponteiro para o bloco de memória a ser liberado. Esse ponteiro é retornado pela função HeapAlloc ou HeapReAlloc . Esse ponteiro pode ser NULL.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Um aplicativo pode chamar GetLastError para obter informações de erro estendidas.

Comentários

Você não deve se referir de forma alguma à memória que foi liberada pelo HeapFree. Depois que essa memória é liberada, qualquer informação que possa ter estado nela se foi para sempre. Se você precisar de informações, não libere a memória que contém as informações. Chamadas de função que retornam informações sobre memória (como HeapSize) podem não ser usadas com memória liberada, pois podem retornar dados falsos. Chamar HeapFree duas vezes com o mesmo ponteiro pode causar corrupção de heap, resultando em chamadas subsequentes para HeapAlloc retornando o mesmo ponteiro duas vezes.

A serialização garante a exclusão mútua quando dois ou mais threads tentam alocar simultaneamente ou liberar blocos do mesmo heap. Há um pequeno custo de desempenho para serialização, mas ele deve ser usado sempre que vários threads alocam e liberam memória do mesmo heap. Definir o valor HEAP_NO_SERIALIZE elimina a exclusão mútua no heap. Sem serialização, dois ou mais threads que usam o mesmo identificador de heap podem tentar alocar ou liberar memória simultaneamente, provavelmente causando corrupção no heap. O valor HEAP_NO_SERIALIZE pode, portanto, ser usado com segurança apenas nas seguintes situações:

O processo tem apenas um thread.
O processo tem vários threads, mas apenas um thread chama as funções de heap para um heap específico.
O processo tem vários threads e o aplicativo fornece seu próprio mecanismo para exclusão mútua para um heap específico.

Exemplos

Para obter um exemplo, consulte Obtendo heaps de processo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	heapapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll