Função HeapAlloc (heapapi.h)

Artigo
02/02/2024

Aloca um bloco de memória de um heap. A memória alocada não é móvel.

Sintaxe

DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags,
  [in] SIZE_T dwBytes
);

Parâmetros

[in] hHeap

Um identificador para o heap do qual a memória será alocada. Esse identificador é retornado pela função HeapCreate ou GetProcessHeap .

[in] dwFlags

As opções de alocação de heap. Especificar qualquer um desses valores substituirá o valor correspondente especificado quando o heap foi criado com HeapCreate. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
HEAP_GENERATE_EXCEPTIONS 0x00000004	O sistema gerará uma exceção para indicar uma falha de função, como uma condição fora da memória, em vez de retornar NULL. Para garantir que exceções sejam geradas para todas as chamadas para essa função, especifique HEAP_GENERATE_EXCEPTIONS na chamada para HeapCreate. Nesse caso, não é necessário especificar adicionalmente HEAP_GENERATE_EXCEPTIONS nessa chamada de função.
HEAP_NO_SERIALIZE 0x00000001	O acesso serializado não será usado para essa alocação. 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.
HEAP_ZERO_MEMORY 0x00000008	A memória alocada será inicializada como zero. Caso contrário, a memória não será inicializada como zero.

Valor

Significado

HEAP_GENERATE_EXCEPTIONS
0x00000004

O sistema gerará uma exceção para indicar uma falha de função, como uma condição fora da memória, em vez de retornar NULL.

Para garantir que exceções sejam geradas para todas as chamadas para essa função, especifique HEAP_GENERATE_EXCEPTIONS na chamada para HeapCreate. Nesse caso, não é necessário especificar adicionalmente HEAP_GENERATE_EXCEPTIONS nessa chamada de função.

HEAP_NO_SERIALIZE
0x00000001

O acesso serializado não será usado para essa alocação.

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.

HEAP_ZERO_MEMORY
0x00000008

A memória alocada será inicializada como zero. Caso contrário, a memória não será inicializada como zero.

[in] dwBytes

O número de bytes a serem alocados.

Se o heap especificado pelo parâmetro hHeap for um heap "não growable", dwBytes deverá ser menor que 0x7FFF8. Você cria um heap não growable chamando a função HeapCreate com um valor diferente de zero.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um ponteiro para o bloco de memória alocado.

Se a função falhar e você não tiver especificado HEAP_GENERATE_EXCEPTIONS, o valor retornado será NULL.

Se a função falhar e você tiver especificado HEAP_GENERATE_EXCEPTIONS, a função poderá gerar uma das exceções listadas na tabela a seguir. A exceção específica depende da natureza da corrupção do heap. Para obter mais informações, consulte GetExceptionCode.

Código da exceção	Descrição
STATUS_NO_MEMORY	A tentativa de alocação falhou devido à falta de memória disponível ou corrupção de heap.
STATUS_ACCESS_VIOLATION	A tentativa de alocação falhou devido à corrupção de heap ou a parâmetros de função inadequados.

Se a função falhar, ela não chamará SetLastError. Um aplicativo não pode chamar GetLastError para obter informações de erro estendidas.

Comentários

Se a função HeapAlloc for bem-sucedida, ela alocará pelo menos a quantidade de memória solicitada.

Para alocar memória do heap padrão do processo, use HeapAlloc com o identificador retornado pela função GetProcessHeap .

Para liberar um bloco de memória alocado pelo HeapAlloc, use a função HeapFree .

A memória alocada por HeapAlloc não é móvel. O endereço retornado por HeapAlloc é válido até que o bloco de memória seja liberado ou realocado; o bloco de memória não precisa ser bloqueado. Como o sistema não pode compactar um heap privado, ele pode ficar fragmentado.

O alinhamento da memória retornada por HeapAlloc é MEMORY_ALLOCATION_ALIGNMENT em WinNT.h:

#if defined(_WIN64) || defined(_M_ALPHA)
#define MEMORY_ALLOCATION_ALIGNMENT 16
#else
#define MEMORY_ALLOCATION_ALIGNMENT 8
#endif

Aplicativos que alocam grandes quantidades de memória em vários tamanhos de alocação podem usar o heap de baixa fragmentação para reduzir a fragmentação de heap.

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 a um heap específico.

Exemplos

Para obter um exemplo, consulte Exemplo de AWE.

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