Funzione HeapFree (heapapi.h)

Articolo
02/02/2024

Libera un blocco di memoria allocato da un heap dalla funzione HeapAlloc o HeapReAlloc .

Sintassi

BOOL HeapFree(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem
);

Parametri

[in] hHeap

Handle per l'heap il cui blocco di memoria deve essere liberato. Questo handle viene restituito dalla funzione HeapCreate o GetProcessHeap .

[in] dwFlags

Opzioni gratuite dell'heap. Se si specifica il valore seguente, viene eseguito l'override del valore corrispondente specificato nel parametro flOptions quando l'heap è stato creato usando la funzione HeapCreate .

Valore	Significato
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. Non specificare questo valore 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.

Valore

Significato

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.

Non specificare questo valore 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.

[in] lpMem

Puntatore al blocco di memoria da liberare. Questo puntatore viene restituito dalla funzione HeapAlloc o HeapReAlloc . Questo puntatore può essere NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Un'applicazione può chiamare GetLastError per informazioni estese sull'errore.

Commenti

Non è consigliabile fare riferimento in alcun modo alla memoria liberata da HeapFree. Dopo che la memoria viene liberata, tutte le informazioni che potrebbero essere state in esso sono andate per sempre. Se sono necessarie informazioni, non liberare memoria contenente le informazioni. Le chiamate di funzione che restituiscono informazioni sulla memoria (ad esempio HeapSize) potrebbero non essere usate con memoria liberata, perché potrebbero restituire dati fittizi. La chiamata a HeapFree due volte con lo stesso puntatore può causare il danneggiamento dell'heap, causando chiamate successive a HeapAlloc restituendo lo stesso puntatore due volte.

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 Getting Process Heaps .For an example, see Getting Process Heaps.

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