Condividi tramite


Funzione HeapReAlloc (heapapi.h)

Rialloca un blocco di memoria da un heap. Questa funzione consente di ridimensionare un blocco di memoria e modificare altre proprietà del blocco di memoria. La memoria allocata non è mobile.

Sintassi

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

Parametri

[in] hHeap

Handle per l'heap da cui deve essere riallocata la memoria. Questo handle viene restituito dalla funzione HeapCreate o GetProcessHeap .

[in] dwFlags

Opzioni di riallocazione dell'heap. Se si specifica un valore, viene eseguito l'override del valore corrispondente specificato nel parametro flOptions quando l'heap è stato creato usando la funzione HeapCreate . Questo parametro può essere uno o più dei valori seguenti.

Valore Significato
HEAP_GENERATE_EXCEPTIONS
0x00000004
Il sistema operativo genera un'eccezione per indicare un errore di funzione, ad esempio una condizione di memoria insufficiente, anziché restituire NULL.

Per assicurarsi che vengano generate eccezioni per tutte le chiamate a questa funzione, specificare HEAP_GENERATE_EXCEPTIONS nella chiamata a HeapCreate. In questo caso, non è necessario specificare HEAP_GENERATE_EXCEPTIONS in questa chiamata di funzione.

HEAP_NO_SERIALIZE
0x00000001
L'accesso serializzato non verrà utilizzato. Per altre informazioni, vedere la sezione Osservazioni.

Per garantire che l'accesso serializzato sia disabilitato per tutte le chiamate a questa funzione, specificare HEAP_NO_SERIALIZE nella chiamata a HeapCreate. In questo caso, non è necessario specificare HEAP_NO_SERIALIZE in questa chiamata di funzione.

Questo valore non deve essere specificato quando si accede all'heap del processo. Il sistema può creare thread aggiuntivi all'interno del processo dell'applicazione, ad esempio un gestore CTRL+C, che accede contemporaneamente all'heap del processo.

HEAP_REALLOC_IN_PLACE_ONLY
0x00000010
Non può esserci alcun movimento durante la riallocazione di un blocco di memoria. Se questo valore non viene specificato, la funzione può spostare il blocco in una nuova posizione. Se questo valore viene specificato e il blocco non può essere ridimensionato senza lo spostamento, la funzione ha esito negativo, lasciando invariato il blocco di memoria originale.
HEAP_ZERO_MEMORY
0x00000008
Se la richiesta di riallocazione è destinata a dimensioni maggiori, l'area aggiuntiva di memoria oltre le dimensioni originali viene inizializzata su zero. Il contenuto del blocco di memoria fino alle dimensioni originali non è interessato.

[in] lpMem

Puntatore al blocco di memoria riallocato dalla funzione. Questo puntatore viene restituito da una chiamata precedente alla funzione HeapAlloc o HeapReAlloc .

[in] dwBytes

Nuova dimensione del blocco di memoria, in byte. Le dimensioni di un blocco di memoria possono essere aumentate o ridotte usando questa funzione.

Se l'heap specificato dal parametro hHeap è un heap "non espadibile", dwBytes deve essere minore di 0x7FFF8. Per creare un heap non scalabile, chiamare la funzione HeapCreate con un valore diverso da zero.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un puntatore al blocco di memoria riallocato.

Se la funzione ha esito negativo e non è stata specificata HEAP_GENERATE_EXCEPTIONS, il valore restituito è NULL.

Se la funzione ha esito negativo e si è specificato HEAP_GENERATE_EXCEPTIONS, la funzione può generare una delle eccezioni elencate nella tabella seguente. Per altre informazioni, vedere GetExceptionCode.

Codice eccezione Descrizione
STATUS_NO_MEMORY Il tentativo di allocazione non è riuscito a causa di un danneggiamento della memoria o dell'heap disponibile.
STATUS_ACCESS_VIOLATION Il tentativo di allocazione non è riuscito a causa del danneggiamento dell'heap o di parametri di funzione non appropriati.

L'allineamento della memoria restituito da HeapReAlloc è MEMORY_ALLOCATION_ALIGNMENT in WinNT.h:

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

Se la funzione non riesce, non chiama SetLastError. Un'applicazione non può chiamare GetLastError per informazioni sugli errori estese.

Commenti

Se HeapReAlloc ha esito positivo, alloca almeno la quantità di memoria richiesta.

Se HeapReAlloc ha esito negativo, la memoria originale non viene liberata e l'handle e il puntatore originali sono ancora validi.

HeapReAlloc garantisce di mantenere il contenuto della memoria riallocata, anche se la nuova memoria viene allocata in una posizione diversa. Il processo di mantenimento del contenuto della memoria comporta un'operazione di copia della memoria potenzialmente dispendiosa in termini di tempo.

Per liberare un blocco di memoria allocato da HeapReAlloc, usare la funzione HeapFree .

La serializzazione garantisce l'esclusione reciproca quando due o più thread tentano di allocare o liberare blocchi contemporaneamente dallo stesso heap. La serializzazione prevede un costo di prestazioni ridotto, ma deve essere usata ogni volta che più thread allocano e liberano memoria dallo stesso heap. L'impostazione del valore HEAP_NO_SERIALIZE elimina l'esclusione reciproca nell'heap. Senza serializzazione, due o più thread che usano lo stesso handle heap potrebbero tentare di allocare o liberare memoria contemporaneamente, causando probabilmente un danneggiamento nell'heap. Il valore HEAP_NO_SERIALIZE può pertanto essere usato in modo sicuro solo nelle situazioni seguenti:

  • Il processo ha un solo thread.
  • Il processo ha più thread, ma un solo thread chiama le funzioni dell'heap per un heap specifico.
  • Il processo ha più thread e l'applicazione fornisce il proprio meccanismo per l'esclusione reciproca a un heap specifico.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [app desktop | App UWP]
Server minimo supportato Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione heapapi.h (include Windows.h)
Libreria Kernel32.lib
DLL Kernel32.dll

Vedere anche

Funzioni heap

HeapAlloc

HeapFree

Funzioni di gestione della memoria

API Vertdll disponibili nelle enclave VBS