Funzione HeapAlloc (heapapi.h)
Alloca un blocco di memoria da un heap. La memoria allocata non è mobile.
Sintassi
DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
[in] HANDLE hHeap,
[in] DWORD dwFlags,
[in] SIZE_T dwBytes
);
Parametri
[in] hHeap
Handle per l'heap da cui verrà allocata la memoria. Questo handle viene restituito dalla funzione HeapCreate o GetProcessHeap .
[in] dwFlags
Opzioni di allocazione dell'heap. Se si specifica uno di questi valori, verrà eseguito l'override del valore corrispondente specificato quando l'heap è stato creato con HeapCreate. Questo parametro può essere uno o più dei valori seguenti.
| Valore | Significato |
|---|---|
|
Il sistema genererà 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à usato per questa allocazione.
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 predefinito 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 predefinito del processo. |
|
La memoria allocata verrà inizializzata su zero. In caso contrario, la memoria non viene inizializzata su zero. |
[in] dwBytes
Numero di byte da allocare.
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 allocato.
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. L'eccezione specifica dipende dalla natura del danneggiamento dell'heap. 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. |
Se la funzione non riesce, non chiama SetLastError. Un'applicazione non può chiamare GetLastError per informazioni sugli errori estese.
Commenti
Se la funzione HeapAlloc ha esito positivo, alloca almeno la quantità di memoria richiesta.
Per allocare memoria dall'heap predefinito del processo, usare HeapAlloc con l'handle restituito dalla funzione GetProcessHeap .
Per liberare un blocco di memoria allocato da HeapAlloc, usare la funzione HeapFree .
La memoria allocata da HeapAlloc non è mobile. L'indirizzo restituito da HeapAlloc è valido fino a quando il blocco di memoria non viene liberato o riallocato; il blocco di memoria non deve essere bloccato. Poiché il sistema non può compattare un heap privato, può diventare frammentato.
L'allineamento della memoria restituito da HeapAlloc è MEMORY_ALLOCATION_ALIGNMENT in WinNT.h:
#if defined(_WIN64) || defined(_M_ALPHA)
#define MEMORY_ALLOCATION_ALIGNMENT 16
#else
#define MEMORY_ALLOCATION_ALIGNMENT 8
#endif
Le applicazioni che allocano grandi quantità di memoria in varie dimensioni di allocazione possono usare l'heap a bassa frammentazione per ridurre la frammentazione dell'heap.
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.
Esempio
Per un esempio, vedere Esempio di AWE.
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 |