HeapValidate-Funktion (heapapi.h)

  • Artikel

Überprüft den angegebenen Heap. Die Funktion überprüft alle Speicherblöcke im Heap und überprüft, ob sich die vom Heap-Manager verwalteten Heapsteuerungsstrukturen in einem konsistenten Zustand befinden. Sie können auch die HeapValidate-Funktion verwenden, um einen einzelnen Speicherblock innerhalb eines angegebenen Heaps zu überprüfen, ohne die Gültigkeit des gesamten Heaps zu überprüfen.

Syntax

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

Parameter

[in] hHeap

Ein Handle für den zu überprüfenden Heap. Dieses Handle wird entweder von der HeapCreate- oder getProcessHeap-Funktion zurückgegeben.

[in] dwFlags

Die Heapzugriffsoptionen. Dieser Parameter kann der folgende Wert sein.

Wert Bedeutung
HEAP_NO_SERIALIZE
0x00000001
 Der serialisierte Zugriff wird nicht verwendet. Weitere Informationen finden Sie in den Hinweisen.

Um sicherzustellen, dass der serialisierte Zugriff für alle Aufrufe dieser Funktion deaktiviert ist, geben Sie im Aufruf von HeapCreate HEAP_NO_SERIALIZE an. In diesem Fall ist es nicht erforderlich, HEAP_NO_SERIALIZE in diesem Funktionsaufruf zusätzlich anzugeben.

Dieser Wert sollte beim Zugriff auf den Standardheap des Prozesses nicht angegeben werden. Das System kann zusätzliche Threads im Prozess der Anwendung erstellen, z. B. einen STRG+C-Handler, der gleichzeitig auf den Standardheap des Prozesses zugreift.

[in, optional] lpMem

Ein Zeiger auf einen Speicherblock innerhalb des angegebenen Heaps. Dieser Parameter kann NULL sein.

Wenn dieser Parameter NULL ist, versucht die Funktion, den gesamten von hHeap angegebenen Heap zu überprüfen.

Wenn dieser Parameter nicht NULL ist, versucht die Funktion, den Speicherblock zu überprüfen, auf den lpMem verweist. Es wird nicht versucht, den Rest des Heaps zu überprüfen.

Rückgabewert

Wenn der angegebene Heap oder Speicherblock gültig ist, ist der Rückgabewert ungleich null.

Wenn der angegebene Heap- oder Speicherblock ungültig ist, ist der Rückgabewert 0(0). Auf einem für das Debuggen eingerichteten System zeigt die HeapValidate-Funktion dann Debugmeldungen an, die den ungültigen Teil des Heaps oder Speicherblocks beschreiben, und hält an einem hartcodierten Haltepunkt an, damit Sie das System untersuchen können, um die Quelle der Ungültigkeit zu ermitteln. Die HeapValidate-Funktion legt den letzten Fehlerwert des Threads nicht fest. Es gibt keine erweiterten Fehlerinformationen für diese Funktion. Rufen Sie GetLastError nicht auf.

Hinweise

Die HeapValidate-Funktion ist in erster Linie für das Debuggen nützlich, da die Validierung möglicherweise zeitaufwändig ist. Die Validierung eines Heaps kann den Zugriff anderer Threads auf den Heap blockieren und die Leistung beeinträchtigen, insbesondere auf SMP-Computern (Symmetric Multiprocessing). Diese Nebenwirkungen können anhalten, bis HeapValidate zurückgibt.

Es gibt Heapsteuerungsstrukturen für jeden Speicherblock in einem Heap und für den Heap als Ganzes. Wenn Sie die HeapValidate-Funktion verwenden, um einen vollständigen Heap zu überprüfen, werden alle diese Kontrollstrukturen auf Konsistenz überprüft.

Wenn Sie HeapValidate verwenden, um einen einzelnen Speicherblock innerhalb eines Heaps zu überprüfen, überprüft er nur die Steuerungsstrukturen, die sich auf dieses Element beziehen. HeapValidate kann nur zugeordnete Speicherblöcke überprüfen. Wenn HeapValidate für einen freigegebenen Speicherblock aufgerufen wird, wird FALSE zurückgegeben, da keine Kontrollstrukturen zu überprüfen sind.

Wenn Sie die von der HeapWalk-Funktion aufgezählten Heapelemente überprüfen möchten, sollten Sie HeapValidate nur für die Elemente aufrufen, die imwFlags-Member der PROCESS_HEAP_ENTRY-Struktur PROCESS_HEAP_ENTRY_BUSY haben. HeapValidate gibt FALSE für alle Heapelemente zurück, für die dieses Bit nicht festgelegt ist.

Durch die Serialisierung wird ein gegenseitiger Ausschluss sichergestellt, wenn zwei oder mehr Threads versuchen, gleichzeitig Blöcke aus demselben Heap zuzuweisen oder frei zu geben. Die Serialisierung verursacht geringe Leistungskosten, muss jedoch immer verwendet werden, wenn mehrere Threads Arbeitsspeicher aus demselben Heap zuweisen und freigeben. Das Festlegen des HEAP_NO_SERIALIZE Werts beseitigt den gegenseitigen Ausschluss auf dem Heap. Ohne Serialisierung können zwei oder mehr Threads, die dasselbe Heaphandle verwenden, versuchen, gleichzeitig Arbeitsspeicher zuzuweisen oder freizugeben, was wahrscheinlich zu Einer Beschädigung des Heaps führt. Der HEAP_NO_SERIALIZE-Wert kann daher nur in den folgenden Situationen sicher verwendet werden:

  • Der Prozess verfügt nur über einen Thread.
  • Der Prozess verfügt über mehrere Threads, aber nur ein Thread ruft die Heapfunktionen für einen bestimmten Heap auf.
  • Der Prozess verfügt über mehrere Threads, und die Anwendung bietet einen eigenen Mechanismus für den gegenseitigen Ausschluss in einen bestimmten Heap.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile heapapi.h (windows.h einschließen)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

Heapfunktionen

HeapCreate

HeapWalk

Speicherverwaltungsfunktionen

PROCESS_HEAP_ENTRY