HeapReAlloc-Funktion (heapapi.h)

  • Artikel

Ordnet einen Speicherblock aus einem Heap neu zu. Mit dieser Funktion können Sie die Größe eines Speicherblocks ändern und andere Speicherblockeigenschaften ändern. Der zugeordnete Arbeitsspeicher kann nicht verschoben werden.

Syntax

DECLSPEC_ALLOCATOR LPVOID HeapReAlloc(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem,
  [in] SIZE_T                 dwBytes
);

Parameter

[in] hHeap

Ein Handle für den Heap, aus dem der Speicher neu zugeordnet werden soll. Dieses Handle wird entweder von der HeapCreate - oder getProcessHeap-Funktion zurückgegeben.

[in] dwFlags

Die Optionen für die Heap-Neuzuordnung. Die Angabe eines Werts überschreibt den entsprechenden Wert, der im flOptions-Parameter angegeben wurde, wenn der Heap mithilfe der HeapCreate-Funktion erstellt wurde. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert Bedeutung
HEAP_GENERATE_EXCEPTIONS
0x00000004
 Das Betriebssystem löst eine Ausnahme aus, um auf einen Funktionsfehler hinzuweisen, z. B. eine Nicht-Arbeitsspeicherbedingung, anstatt NULL zurückzugeben.

Um sicherzustellen, dass für alle Aufrufe dieser Funktion Ausnahmen generiert werden, geben Sie im Aufruf von HeapCreate HEAP_GENERATE_EXCEPTIONS an. In diesem Fall ist es nicht erforderlich, in diesem Funktionsaufruf zusätzlich HEAP_GENERATE_EXCEPTIONS anzugeben.
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 Prozessheap nicht angegeben werden. Das System kann zusätzliche Threads im Prozess der Anwendung erstellen, z. B. einen STRG+C-Handler, der gleichzeitig auf den Prozessheap zugreift.
HEAP_REALLOC_IN_PLACE_ONLY
0x00000010
 Es kann keine Bewegung geben, wenn ein Speicherblock neu zugeordnet wird. Wenn dieser Wert nicht angegeben wird, kann die Funktion den Block an eine neue Position verschieben. Wenn dieser Wert angegeben wird und die Größe des Blocks ohne Verschieben nicht geändert werden kann, schlägt die Funktion fehl, sodass der ursprüngliche Speicherblock unverändert bleibt.
HEAP_ZERO_MEMORY
0x00000008
 Wenn die Neuzuweisungsanforderung für eine größere Größe gilt, wird der zusätzliche Speicherbereich, der über die ursprüngliche Größe hinaus liegt, auf 0 (null) initialisiert. Der Inhalt des Speicherblocks bis zu seiner ursprünglichen Größe ist nicht betroffen.

[in] lpMem

Ein Zeiger auf den Speicherblock, den die Funktion neu zuordnet. Dieser Zeiger wird durch einen früheren Aufruf der HeapAlloc - oder HeapReAlloc-Funktion zurückgegeben.

[in] dwBytes

Die neue Größe des Speicherblocks in Bytes. Die Größe eines Speicherblocks kann mithilfe dieser Funktion vergrößert oder verringert werden.

Wenn der durch den hHeap-Parameter angegebene Heap ein "nicht anwachsenbarer" Heap ist, muss dwBytes kleiner als 0x7FFF8 sein. Sie erstellen einen nicht anwachsenden Heap, indem Sie die HeapCreate-Funktion mit einem Wert ungleich null aufrufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Zeiger auf den neu 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. Weitere Informationen finden Sie unter GetExceptionCode.

Ausnahmecode BESCHREIBUNG
STATUS_NO_MEMORY Der Zuordnungsversuch ist aufgrund eines Mangels an verfügbarem Arbeitsspeicher oder heapbeschädigung fehlgeschlagen.
STATUS_ACCESS_VIOLATION Der Zuordnungsversuch ist aufgrund einer Heapbeschädigung oder falscher Funktionsparameter fehlgeschlagen.

Die Ausrichtung des von HeapReAlloc 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

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

Hinweise

Wenn HeapReAlloc erfolgreich ist, wird mindestens die angeforderte Arbeitsspeichermenge zugeordnet.

Wenn HeapReAlloc fehlschlägt, wird der ursprüngliche Speicher nicht freigegeben, und das ursprüngliche Handle und der Zeiger sind weiterhin gültig.

HeapReAlloc behält den Inhalt des neu zugeordneten Speichers garantiert bei, auch wenn der neue Speicher an einem anderen Speicherort zugeordnet wird. Der Prozess zum Beibehalten des Speicherinhalts umfasst einen Speicherkopiervorgang, der möglicherweise sehr zeitaufwändig ist.

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

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

HeapAlloc

HeapFree

Speicherverwaltungsfunktionen

In VBS-Enclaves verfügbare Vertdll-APIs