HeapCompact-Funktion (heapapi.h)

Gibt die Größe des größten frei committeten Blocks im angegebenen Heap zurück. Wenn das Flag Heap-Zusammenführung für freies globales Feature deaktivieren festgelegt ist, werden mit dieser Funktion auch benachbarte freie Speicherblöcke im Heap zusammengelegt.

Syntax

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

Parameter

[in] hHeap

Ein Handle für den 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. Geben Sie diesen Wert beim Zugriff auf den Prozessheap nicht an. Das System kann zusätzliche Threads im Prozess der Anwendung erstellen, z. B. einen STRG+C-Handler, der gleichzeitig auf den Prozessheap zugreift.

Rückgabewert

Wenn die Funktion erfolgreich ist, entspricht der Rückgabewert der Größe des größten committeten freien Blocks im Heap in Bytes.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

In dem unwahrscheinlichen Fall, dass im Heap absolut kein Speicherplatz verfügbar ist, ist der Rückgabewert der Funktion Null, und GetLastError gibt den Wert NO_ERROR zurück.

Hinweise

Die HeapCompact-Funktion ist in erster Linie für das Debuggen nützlich. Normalerweise komprimiert das System den Heap, wenn die HeapFree-Funktion aufgerufen wird, und die HeapCompact-Funktion gibt die Größe des größten freien Blocks im Heap zurück, komprimiert den Heap jedoch nicht weiter. Wenn während des Debuggens das Flag Disable heap coalesce on free global festgelegt ist, komprimiert das System den Heap nicht, und der Aufruf der HeapCompact-Funktion komprimiert den Heap. Weitere Informationen zu globalen Flags finden Sie in der GFlags-Dokumentation .

Es gibt keine Garantie, dass eine Anwendung einen Speicherblock der von HeapCompact zurückgegebenen Größe erfolgreich zuordnen kann. Andere Threads oder der Commitschwellenwert können eine solche Zuordnung verhindern.

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 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform	Windows
Kopfzeile	heapapi.h (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Siehe auch

Heapfunktionen

HeapCreate

HeapValidate

Speicherverwaltungsfunktionen

In VBS-Enclaves verfügbare Vertdll-APIs