HeapAlloc-Funktion (heapapi.h)

Ordnet einen Speicherblock aus einem Heap zu. Der zugewiesene Arbeitsspeicher ist nicht verschiebbar.

Syntax

DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags,
  [in] SIZE_T dwBytes
);

Parameter

[in] hHeap

Ein Handle für den Heap, aus dem der Arbeitsspeicher zugewiesen wird. Dieses Handle wird von der HeapCreate - oder GetProcessHeap-Funktion zurückgegeben.

[in] dwFlags

Die Heapzuordnungsoptionen. Wenn Sie einen dieser Werte angeben, wird der entsprechende Wert überschrieben, der beim Erstellen des Heaps mit HeapCreate angegeben wurde. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
HEAP_GENERATE_EXCEPTIONS 0x00000004	Das System löst eine Ausnahme aus, um auf einen Funktionsfehler hinzuweisen, z. B. eine Bedingung außerhalb des Arbeitsspeichers, anstatt NULL zurückzugeben. Um sicherzustellen, dass Ausnahmen für alle Aufrufe dieser Funktion generiert werden, geben Sie im Aufruf von HeapCreateHEAP_GENERATE_EXCEPTIONS an. In diesem Fall ist es nicht erforderlich, HEAP_GENERATE_EXCEPTIONS in diesem Funktionsaufruf zusätzlich anzugeben.
HEAP_NO_SERIALIZE 0x00000001	Der serialisierte Zugriff wird für diese Zuordnung 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 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 zugreifen kann.
HEAP_ZERO_MEMORY 0x00000008	Der zugewiesene Arbeitsspeicher wird mit 0 initialisiert. Andernfalls wird der Arbeitsspeicher nicht auf null initialisiert.

[in] dwBytes

Die Anzahl der zuzuordnenden Bytes.

Wenn der durch den hHeap-Parameter angegebene Heap ein heap ist, der nicht wachsen kann, muss dwBytes kleiner als 0x7FFF8 sein. Sie erstellen einen nicht erweiterbaren Heap, indem Sie die HeapCreate-Funktion mit einem Nonzero-Wert aufrufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Zeiger auf den zugeordneten Speicherblock.

Wenn die Funktion fehlschlägt und Sie HEAP_GENERATE_EXCEPTIONS nicht angegeben haben, ist der Rückgabewert NULL.

Wenn die Funktion fehlschlägt und Sie HEAP_GENERATE_EXCEPTIONS angegeben haben, generiert die Funktion möglicherweise eine der in der folgenden Tabelle aufgeführten Ausnahmen. Die besondere Ausnahme hängt von der Art der Heapbeschädigung ab. Weitere Informationen finden Sie unter GetExceptionCode.

Ausnahmecode	BESCHREIBUNG
STATUS_NO_MEMORY	Der Zuordnungsversuch ist aufgrund eines Mangels an verfügbarem Arbeitsspeicher oder einer Heapbeschädigung fehlgeschlagen.
STATUS_ACCESS_VIOLATION	Der Zuordnungsversuch ist aufgrund von Heapbeschädigung oder falschen Funktionsparametern fehlgeschlagen.

Wenn die Funktion fehlschlägt, wird SetLastError nicht aufgerufen. Eine Anwendung kann GetLastError nicht für erweiterte Fehlerinformationen aufrufen.

Hinweise

Wenn die HeapAlloc-Funktion erfolgreich ist, werden mindestens die angeforderte Arbeitsspeichermenge zugeordnet.

Um Arbeitsspeicher aus dem Standardheap des Prozesses zuzuweisen, verwenden Sie HeapAlloc mit dem von der GetProcessHeap-Funktion zurückgegebenen Handle.

Verwenden Sie die HeapFree-Funktion, um einen von HeapAlloc zugewiesenen Speicherblock freizugeben.

Der von HeapAlloc zugewiesene Arbeitsspeicher ist nicht verschiebbar. Die von HeapAlloc zurückgegebene Adresse ist gültig, bis der Speicherblock freigegeben oder neu zugewiesen wurde. Der Speicherblock muss nicht gesperrt werden. Da das System einen privaten Heap nicht komprimieren kann, kann er fragmentiert werden.

Die Ausrichtung des von HeapAlloc zurückgegebenen Arbeitsspeichers wird in WinNT.h MEMORY_ALLOCATION_ALIGNMENT :

#if defined(_WIN64) || defined(_M_ALPHA)
#define MEMORY_ALLOCATION_ALIGNMENT 16
#else
#define MEMORY_ALLOCATION_ALIGNMENT 8
#endif

Anwendungen, die große Mengen an Arbeitsspeicher in verschiedenen Zuordnungsgrößen zuweisen, können den Heap mit geringer Fragmentierung verwenden, um die Heapfragmentierung zu reduzieren.

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.

Beispiele

Ein Beispiel finden Sie unter AWE-Beispiel.

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

HeapFree

HeapReAlloc

Speicherverwaltungsfunktionen

In VBS-Enklaven verfügbare Vertdll-APIs