Funzione HeapCompact (heapapi.h)

Articolo
08/15/2024

Restituisce le dimensioni del blocco gratuito commit più grande nell'heap specificato. Se viene impostata la Disabilita unione dell'heap su flag globale gratuito, questa funzione coalizza anche blocchi di memoria liberi adiacenti nell'heap.

Sintassi

SIZE_T HeapCompact(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags
);

Parametri

[in] hHeap

Handle per l'heap. Questo handle viene restituito dalla funzione HeapCreate o GetProcessHeap.

[in] dwFlags

Opzioni di accesso all'heap. Questo parametro può essere il valore seguente.

Valore	Significato
HEAP_NO_SERIALIZE 0x00000001	L'accesso serializzato non verrà utilizzato. Per altre informazioni, vedere Osservazioni. Per assicurarsi che l'accesso serializzato sia disabilitato per tutte le chiamate a questa funzione, specificare HEAP_NO_SERIALIZE nella chiamata a HeapCreare. 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 accedono contemporaneamente all'heap del processo.

Valore

Significato

HEAP_NO_SERIALIZE
0x00000001

L'accesso serializzato non verrà utilizzato.

Per altre informazioni, vedere Osservazioni.

Per assicurarsi che l'accesso serializzato sia disabilitato per tutte le chiamate a questa funzione, specificare HEAP_NO_SERIALIZE nella chiamata a HeapCreare. 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 accedono contemporaneamente all'heap del processo.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è la dimensione del blocco gratuito di commit più grande nell'heap, in byte.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Nel caso improbabile che non sia disponibile spazio nell'heap, il valore restituito della funzione è zero e GetLastError restituisce il valore NO_ERROR.

Osservazioni

La funzione heapCompact è utile principalmente per il debug. In genere, il sistema compatta l'heap ogni volta che viene chiamata la funzione HeapFree e la funzione HeapCompact restituisce le dimensioni del blocco libero più grande nell'heap, ma non compatta ulteriormente l'heap. Se durante il debug viene impostata la Disabilita unione dell'heap in flag globale gratuito, il sistema non compatta l'heap e chiama la funzione HeapCompact compatta l'heap. Per altre informazioni sui flag globali, vedere la documentazione GFlags.

Non è garantito che un'applicazione possa allocare correttamente un blocco di memoria delle dimensioni restituite da HeapCompact. Altri thread o la soglia di commit potrebbero impedire tale allocazione.

La serializzazione garantisce l'esclusione reciproca quando due o più thread tentano di allocare o liberare contemporaneamente blocchi 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 il 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 in un heap specifico.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	heapapi.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll

Vedere anche

funzioni heap

HeapCreare

heapValidate

funzioni di gestione della memoria

API Vertdll disponibili nelle enclave VBS

Condividi tramite