Função HeapCreate (heapapi.h)

Artigo
02/02/2024

Cria um objeto de heap privado que pode ser usado pelo processo de chamada. A função reserva espaço no espaço de endereço virtual do processo e aloca armazenamento físico para uma parte inicial especificada desse bloco.

Sintaxe

HANDLE HeapCreate(
  [in] DWORD  flOptions,
  [in] SIZE_T dwInitialSize,
  [in] SIZE_T dwMaximumSize
);

Parâmetros

[in] flOptions

As opções de alocação de heap. Essas opções afetam o acesso subsequente ao novo heap por meio de chamadas para as funções de heap. Esse parâmetro pode ser 0 ou um ou mais dos valores a seguir.

Valor	Significado
HEAP_CREATE_ENABLE_EXECUTE 0x00040000	Todos os blocos de memória alocados desse heap permitem a execução de código, se o hardware impõe a prevenção de execução de dados. Use esse heap de sinalizador em aplicativos que executam código do heap. Se HEAP_CREATE_ENABLE_EXECUTE não for especificado e um aplicativo tentar executar o código de uma página protegida, o aplicativo receberá uma exceção com o código status STATUS_ACCESS_VIOLATION.
HEAP_GENERATE_EXCEPTIONS 0x00000004	O sistema gera uma exceção para indicar falha (por exemplo, uma condição de memória insuficiente) para chamadas para HeapAlloc e HeapReAlloc em vez de retornar NULL.
HEAP_NO_SERIALIZE 0x00000001	O acesso serializado não é usado quando as funções de heap acessam esse heap. Essa opção se aplica a todas as chamadas de função heap subsequentes. Como alternativa, você pode especificar essa opção em chamadas de função de heap individuais. O heap de baixa fragmentação (LFH) não pode ser habilitado para um heap criado com essa opção. Um heap criado com essa opção não pode ser bloqueado. Para obter mais informações sobre o acesso serializado, consulte a seção Comentários deste tópico.

Valor

Significado

HEAP_CREATE_ENABLE_EXECUTE
0x00040000

Todos os blocos de memória alocados desse heap permitem a execução de código, se o hardware impõe a prevenção de execução de dados. Use esse heap de sinalizador em aplicativos que executam código do heap. Se HEAP_CREATE_ENABLE_EXECUTE não for especificado e um aplicativo tentar executar o código de uma página protegida, o aplicativo receberá uma exceção com o código status STATUS_ACCESS_VIOLATION.

HEAP_GENERATE_EXCEPTIONS
0x00000004

O sistema gera uma exceção para indicar falha (por exemplo, uma condição de memória insuficiente) para chamadas para HeapAlloc e HeapReAlloc em vez de retornar NULL.

HEAP_NO_SERIALIZE
0x00000001

O acesso serializado não é usado quando as funções de heap acessam esse heap. Essa opção se aplica a todas as chamadas de função heap subsequentes. Como alternativa, você pode especificar essa opção em chamadas de função de heap individuais.

O heap de baixa fragmentação (LFH) não pode ser habilitado para um heap criado com essa opção.

Um heap criado com essa opção não pode ser bloqueado.

Para obter mais informações sobre o acesso serializado, consulte a seção Comentários deste tópico.

[in] dwInitialSize

O tamanho inicial do heap, em bytes. Esse valor determina a quantidade inicial de memória confirmada para o heap. O valor é arredondado para um múltiplo do tamanho da página do sistema. O valor deve ser menor que dwMaximumSize.

Se esse parâmetro for 0, a função confirmará uma página. Para determinar o tamanho de uma página no computador host, use a função GetSystemInfo .

[in] dwMaximumSize

O tamanho máximo do heap, em bytes. A função HeapCreate arredonda dwMaximumSize até um múltiplo do tamanho da página do sistema e reserva um bloco desse tamanho no espaço de endereço virtual do processo para o heap. Se as solicitações de alocação feitas pelas funções HeapAlloc ou HeapReAlloc excederem o tamanho especificado por dwInitialSize, o sistema confirmará páginas adicionais de memória para o heap, até o tamanho máximo do heap.

Se dwMaximumSize não for zero, o tamanho do heap será fixo e não poderá crescer além do tamanho máximo. Além disso, o maior bloco de memória que pode ser alocado do heap é um pouco menor que 512 KB para um processo de 32 bits e um pouco menos de 1.024 KB para um processo de 64 bits. As solicitações para alocar blocos maiores falharão, mesmo que o tamanho máximo do heap seja grande o suficiente para conter o bloco.

Se dwMaximumSize for 0, o heap poderá aumentar de tamanho. O tamanho do heap é limitado apenas pela memória disponível. As solicitações para alocar blocos de memória maiores que o limite de um heap de tamanho fixo não falham automaticamente; Em vez disso, o sistema chama a função VirtualAlloc para obter a memória necessária para blocos grandes. Os aplicativos que precisam alocar blocos de memória grandes devem definir dwMaximumSize como 0.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o heap recém-criado.

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

Comentários

A função HeapCreate cria um objeto heap privado do qual o processo de chamada pode alocar blocos de memória usando a função HeapAlloc . O tamanho inicial determina o número de páginas confirmadas alocadas inicialmente para o heap. O tamanho máximo determina o número total de páginas reservadas. Essas páginas criam um bloco no espaço de endereço virtual do processo no qual o heap pode crescer. Se as solicitações de HeapAlloc excederem o tamanho atual das páginas confirmadas, páginas adicionais serão confirmadas automaticamente desse espaço reservado, se o armazenamento físico estiver disponível.

Windows Server 2003 e Windows XP: Por padrão, o heap privado recém-criado é um heap padrão. Para habilitar o heap de baixa fragmentação, chame a função HeapSetInformation com um identificador para o heap privado.

A memória de um objeto de heap privado é acessível somente ao processo que o criou. Se uma DLL (biblioteca de vínculo dinâmico) criar um heap privado, o heap será criado no espaço de endereço do processo que chama a DLL e estará acessível somente para esse processo.

O sistema usa memória do heap privado para armazenar estruturas de suporte de heap, portanto, nem todo o tamanho de heap especificado está disponível para o processo. Por exemplo, se a função HeapAlloc solicitar 64 quilobytes (K) de um heap com um tamanho máximo de 64K, a solicitação poderá falhar devido à sobrecarga do sistema.

Se HEAP_NO_SERIALIZE não for especificado (o padrão simples), o heap serializará o acesso dentro do processo de chamada. A serialização garante a exclusão mútua quando dois ou mais threads tentam simultaneamente alocar 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. As funções HeapLock e HeapUnlock podem ser usadas para bloquear e permitir o acesso a um heap serializado.

Definir 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, o que pode causar corrupção no heap. Portanto, HEAP_NO_SERIALIZE só podem ser usados com segurança 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.

Se as funções HeapLock e HeapUnlock forem chamadas em um heap criado com o sinalizador HEAP_NO_SERIALIZE , os resultados serão indefinidos.

Para obter um identificador para o heap padrão para um processo, use a função GetProcessHeap . Para obter identificadores para o heap padrão e heaps privados que estão ativos para o processo de chamada, use a função GetProcessHeaps .

Exemplos

Enumerando um heap

Requisitos


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