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 |
|---|---|
|
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. |
|
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. |
|
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 |