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