Função HeapCreate (heapapi.h)

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.

[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

Confira também

Funções heap

Heapalloc

HeapDestroy

HeapValidate

Funções de gerenciamento da memória

APIs Vertdll disponíveis em enclaves de VBS