HeapSize-Funktion (heapapi.h)

  • Artikel

Ruft die Größe eines Speicherblocks ab, der aus einem Heap durch die HeapAlloc - oder HeapReAlloc-Funktion zugeordnet ist.

Syntax

SIZE_T HeapSize(
  [in] HANDLE  hHeap,
  [in] DWORD   dwFlags,
  [in] LPCVOID lpMem
);

Parameter

[in] hHeap

Ein Handle für den Heap, in dem sich der Speicherblock befindet. Dieses Handle wird entweder von der Funktion HeapCreate oder GetProcessHeap zurückgegeben.

[in] dwFlags

Die Heapgrößenoptionen. Wenn Sie den folgenden Wert angeben, wird der entsprechende Wert überschrieben, der im flOptions-Parameter angegeben wurde, als der Heap mithilfe der HeapCreate-Funktion erstellt wurde.

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 HeapCreateHEAP_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 Prozessheap nicht angegeben werden. Das System kann zusätzliche Threads innerhalb des Prozesses der Anwendung erstellen, z. B. einen STRG+C-Handler, der gleichzeitig auf den Prozessheap zugreift.

[in] lpMem

Ein Zeiger auf den Speicherblock, dessen Größe die Funktion erhält. Dies ist ein Zeiger, der von der Funktion HeapAlloc oder HeapReAlloc zurückgegeben wird. Der Speicherblock muss aus dem durch den hHeap-Parameter angegebenen Heap stammen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die angeforderte Größe des zugeordneten Speicherblocks in Bytes.

Wenn die Funktion fehlschlägt, ist (SIZE_T)-1der Rückgabewert . Die Funktion ruft SetLastError nicht auf. Eine Anwendung kann GetLastError nicht für erweiterte Fehlerinformationen aufrufen.

Wenn der lpMem-Parameter auf eine Heapzuordnung verweist, die sich nicht im vom hHeap-Parameter angegebenen Heap befindet, ist das Verhalten der HeapSize-Funktion nicht definiert.

Hinweise

Die Serialisierung stellt einen gegenseitigen Ausschluss sicher, 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 dann verwendet werden, wenn mehrere Threads Arbeitsspeicher aus demselben Heap zuweisen und freizugeben. Durch Festlegen des HEAP_NO_SERIALIZE-Werts wird der gegenseitige Ausschluss auf dem Heap beseitigt. 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 zum gegenseitigen Ausschluss von einem 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 (einschließlich Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

Heapfunktionen

HeapAlloc

HeapReAlloc

Speicherverwaltungsfunktionen

In VBS-Enklaven verfügbare Vertdll-APIs