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
HEAP_GENERATE_EXCEPTIONS 0x00000004	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.
HEAP_NO_SERIALIZE 0x00000001	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.
HEAP_ZERO_MEMORY 0x00000008	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

Vedere anche

Funzioni heap

HeapFree

HeapReAlloc

Funzioni di gestione della memoria

API Vertdll disponibili nelle enclave VBS