Função HeapValidate (heapapi.h)

Artigo
08/24/2023

Valida o heap especificado. A função examina todos os blocos de memória no heap e verifica se as estruturas de controle de heap mantidas pelo gerenciador de heap estão em um estado consistente. Você também pode usar a função HeapValidate para validar um único bloco de memória em um heap especificado sem verificar a validade de todo o heap.

Sintaxe

BOOL HeapValidate(
  [in]           HANDLE  hHeap,
  [in]           DWORD   dwFlags,
  [in, optional] LPCVOID lpMem
);

Parâmetros

[in] hHeap

Um identificador para o heap a ser validado. Esse identificador é retornado pela função HeapCreate ou GetProcessHeap .

[in] dwFlags

As opções de acesso ao heap. Esse parâmetro pode ser o valor a seguir.

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. Esse valor não deve ser especificado ao acessar o heap padrão do processo. O sistema pode criar threads adicionais dentro do processo do aplicativo, como um manipulador CTRL+C, que acessam simultaneamente o heap padrão 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.

Esse valor não deve ser especificado ao acessar o heap padrão do processo. O sistema pode criar threads adicionais dentro do processo do aplicativo, como um manipulador CTRL+C, que acessam simultaneamente o heap padrão do processo.

[in, optional] lpMem

Um ponteiro para um bloco de memória dentro do heap especificado. Esse parâmetro pode ser NULL.

Se esse parâmetro for NULL, a função tentará validar todo o heap especificado por hHeap.

Se esse parâmetro não for NULL, a função tentará validar o bloco de memória apontado por lpMem. Ele não tenta validar o restante do heap.

Retornar valor

Se o heap ou bloco de memória especificado for válido, o valor retornado será diferente de zero.

Se o heap ou bloco de memória especificado for inválido, o valor retornado será zero. Em um sistema configurado para depuração, a função HeapValidate exibe mensagens de depuração que descrevem a parte do heap ou bloco de memória inválido e para em um ponto de interrupção embutido em código para que você possa examinar o sistema para determinar a origem da invalidez. A função HeapValidate não define o último valor de erro do thread. Não há informações de erro estendidas para essa função; não chame GetLastError.

Comentários

A função HeapValidate é útil principalmente para depuração porque a validação é potencialmente demorada. A validação de um heap pode impedir que outros threads acessem o heap e pode prejudicar o desempenho, especialmente em computadores SMP (multiprocessamento simétrico). Esses efeitos colaterais podem durar até que HeapValidate retorne.

Há estruturas de controle de heap para cada bloco de memória em um heap e para o heap como um todo. Quando você usa a função HeapValidate para validar um heap completo, ele verifica a consistência de todas essas estruturas de controle.

Quando você usa HeapValidate para validar um único bloco de memória dentro de um heap, ele verifica apenas as estruturas de controle pertencentes a esse elemento. HeapValidate só pode validar blocos de memória alocados. Chamar HeapValidate em um bloco de memória liberado retornará FALSE porque não há estruturas de controle para validar.

Se você quiser validar os elementos de heap enumerados pela função HeapWalk , só deverá chamar HeapValidate nos elementos que têm PROCESS_HEAP_ENTRY_BUSY no membro wFlags da estrutura PROCESS_HEAP_ENTRY . HeapValidate retorna FALSE para todos os elementos de heap que não têm esse bit definido.

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.

Requisitos

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