Funzione HeapValidate (heapapi.h)

Convalida l'heap specificato. La funzione analizza tutti i blocchi di memoria nell'heap e verifica che le strutture di controllo dell'heap gestite dal gestore dell'heap siano in uno stato coerente. È anche possibile usare la funzione HeapValidate per convalidare un singolo blocco di memoria all'interno di un heap specificato senza controllare la validità dell'intero heap.

Sintassi

BOOL HeapValidate(
  [in]           HANDLE  hHeap,
  [in]           DWORD   dwFlags,
  [in, optional] LPCVOID lpMem
);

Parametri

[in] hHeap

Handle dell'heap da convalidare. Questo handle viene restituito dalla funzione HeapCreate o GetProcessHeap .

[in] dwFlags

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

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. 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 accedono simultaneamente all'heap predefinito del processo.

[in, optional] lpMem

Puntatore a un blocco di memoria all'interno dell'heap specificato. Questo parametro può essere NULL.

Se questo parametro è NULL, la funzione tenta di convalidare l'intero heap specificato da hHeap.

Se questo parametro non è NULL, la funzione tenta di convalidare il blocco di memoria a cui punta lpMem. Non tenta di convalidare il resto dell'heap.

Valore restituito

Se l'heap o il blocco di memoria specificato è valido, il valore restituito è diverso da zero.

Se l'heap o il blocco di memoria specificato non è valido, il valore restituito è zero. In un sistema configurato per il debug, la funzione HeapValidate visualizza quindi i messaggi di debug che descrivono la parte dell'heap o del blocco di memoria non valido e si arresta in corrispondenza di un punto di interruzione hardcoded in modo che sia possibile esaminare il sistema per determinare l'origine della validità. La funzione HeapValidate non imposta l'ultimo valore di errore del thread. Non sono presenti informazioni di errore estese per questa funzione; non chiamare GetLastError.

Commenti

La funzione HeapValidate è utile principalmente per il debug perché la convalida richiede potenzialmente molto tempo. La convalida di un heap può impedire ad altri thread di accedere all'heap e può compromettere le prestazioni, in particolare nei computer SMP (Symmetric MultiProcessing). Questi effetti collaterali possono durare fino a quando HeapValidate restituisce .

Esistono strutture di controllo heap per ogni blocco di memoria in un heap e per l'heap nel suo complesso. Quando si usa la funzione HeapValidate per convalidare un heap completo, verifica la coerenza di tutte queste strutture di controllo.

Quando si usa HeapValidate per convalidare un singolo blocco di memoria all'interno di un heap, controlla solo le strutture di controllo relative a tale elemento. HeapValidate può convalidare solo i blocchi di memoria allocati. La chiamata a HeapValidate in un blocco di memoria liberato restituirà FALSE perché non sono presenti strutture di controllo da convalidare.

Se si desidera convalidare gli elementi heap enumerati dalla funzione HeapWalk , è consigliabile chiamare HeapValidate solo sugli elementi che hanno PROCESS_HEAP_ENTRY_BUSY nel membro wFlags della struttura PROCESS_HEAP_ENTRY . HeapValidate restituisceFALSE per tutti gli elementi dell'heap che non dispongono di questo set di bit.

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 [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	heapapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll

Vedere anche

Funzioni heap

HeapCreate

HeapWalk

Funzioni di gestione della memoria

PROCESS_HEAP_ENTRY