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