Função HeapCompact (heapapi.h)

Retorna o tamanho do maior bloco livre confirmado no heap especificado. Se a opção Desabilitar a união de heap no sinalizador global livre estiver definida, essa função também unirá blocos livres adjacentes de memória no heap.

Sintaxe

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

Parâmetros

[in] hHeap

Um identificador para o heap. 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. 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.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o tamanho do maior bloco livre confirmado no heap, em bytes.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

No caso improvável de que não haja absolutamente nenhum espaço disponível no heap, o valor retornado da função é zero e GetLastError retorna o valor NO_ERROR.

Comentários

A função HeapCompact é útil principalmente para depuração. Normalmente, o sistema compacta o heap sempre que a função HeapFree é chamada e a função HeapCompact retorna o tamanho do maior bloco livre no heap, mas não compacta mais o heap. Se a opção Desabilitar a união de heap no sinalizador global livre for definida durante a depuração, o sistema não compacta o heap e chamar a função HeapCompact compacta o heap. Para obter mais informações sobre sinalizadores globais, consulte a documentação do GFlags .

Não há nenhuma garantia de que um aplicativo possa alocar com êxito um bloco de memória do tamanho retornado por HeapCompact. Outros threads ou o limite de confirmação podem impedir essa alocação.

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 [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

Confira também

Funções heap

Heapcreate

HeapValidate

Funções de gerenciamento da memória

APIs Vertdll disponíveis em enclaves de VBS