Compartilhar via


Função HeapReAlloc (heapapi.h)

Realoca um bloco de memória de um heap. Essa função permite redimensionar um bloco de memória e alterar outras propriedades de bloco de memória. A memória alocada não é móvel.

Sintaxe

DECLSPEC_ALLOCATOR LPVOID HeapReAlloc(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem,
  [in] SIZE_T                 dwBytes
);

Parâmetros

[in] hHeap

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

[in] dwFlags

As opções de realocação de heap. Especificar um valor substitui o valor correspondente especificado no parâmetro flOptions quando o heap foi criado usando a função HeapCreate . Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
HEAP_GENERATE_EXCEPTIONS
0x00000004
O sistema operacional gera uma exceção para indicar uma falha de função, como uma condição de memória insuficiente, 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 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 de processo. O sistema pode criar threads adicionais dentro do processo do aplicativo, como um manipulador CTRL+C, que acessam simultaneamente o heap de processo.

HEAP_REALLOC_IN_PLACE_ONLY
0x00000010
Não pode haver movimento ao realocar um bloco de memória. Se esse valor não for especificado, a função poderá mover o bloco para um novo local. Se esse valor for especificado e o bloco não puder ser redimensionado sem mover, a função falhará, deixando o bloco de memória original inalterado.
HEAP_ZERO_MEMORY
0x00000008
Se a solicitação de realocação for para um tamanho maior, a região adicional de memória além do tamanho original será inicializada como zero. O conteúdo do bloco de memória até seu tamanho original não é afetado.

[in] lpMem

Um ponteiro para o bloco de memória que a função realoca. Esse ponteiro é retornado por uma chamada anterior para a função HeapAlloc ou HeapReAlloc .

[in] dwBytes

O novo tamanho do bloco de memória, em bytes. O tamanho de um bloco de memória pode ser aumentado ou reduzido usando essa função.

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 realocada.

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

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

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

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 HeapReAlloc for bem-sucedido, ele alocará pelo menos a quantidade de memória solicitada.

Se HeapReAlloc falhar, a memória original não será liberada e o identificador original e o ponteiro ainda serão válidos.

HeapReAlloc é garantido para preservar o conteúdo da memória que está sendo realocada, mesmo que a nova memória seja alocada em um local diferente. O processo de preservação do conteúdo da memória envolve uma operação de cópia de memória que é potencialmente muito demorada.

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

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.

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

Heapalloc

Heapfree

Funções de gerenciamento da memória

APIs Vertdll disponíveis em enclaves de VBS