HeapCreate-Funktion (heapapi.h)
Erstellt ein privates Heapobjekt, das vom aufrufenden Prozess verwendet werden kann. Die Funktion reserviert Speicherplatz im virtuellen Adressraum des Prozesses und ordnet physischen Speicher für einen angegebenen Anfangsteil dieses Blocks zu.
Syntax
HANDLE HeapCreate(
[in] DWORD flOptions,
[in] SIZE_T dwInitialSize,
[in] SIZE_T dwMaximumSize
);
Parameter
[in] flOptions
Die Heapzuordnungsoptionen. Diese Optionen wirken sich auf den nachfolgenden Zugriff auf den neuen Heap durch Aufrufe der Heapfunktionen aus. Dieser Parameter kann 0 oder mindestens einer der folgenden Werte sein.
| Wert | Bedeutung |
|---|---|
|
Alle Speicherblöcke, die über diesen Heap zugeordnet werden, lassen die Codeausführung zu, wenn die Hardware die Verhinderung der Datenausführung erzwingt. Verwenden Sie diesen Flagheap in Anwendungen, die Code aus dem Heap ausführen. Wenn HEAP_CREATE_ENABLE_EXECUTE nicht angegeben ist und eine Anwendung versucht, Code von einer geschützten Seite auszuführen, erhält die Anwendung eine Ausnahme mit dem status Code STATUS_ACCESS_VIOLATION. |
|
Das System löst eine Ausnahme aus, um einen Fehler (z. B. eine Bedingung außerhalb des Arbeitsspeichers) für Aufrufe von HeapAlloc und HeapReAlloc anzugeben, anstatt NULL zurückzugeben. |
|
Der serialisierte Zugriff wird nicht verwendet, wenn die Heapfunktionen auf diesen Heap zugreifen. Diese Option gilt für alle nachfolgenden Heap-Funktionsaufrufe. Alternativ können Sie diese Option für einzelne Heapfunktionsaufrufe angeben.
Der Heap mit geringer Fragmentierung (LFH) kann nicht für einen heap aktiviert werden, der mit dieser Option erstellt wurde. Ein mit dieser Option erstelltes Heap kann nicht gesperrt werden. Weitere Informationen zum serialisierten Zugriff finden Sie im Abschnitt Hinweise zu diesem Thema. |
[in] dwInitialSize
Die anfängliche Größe des Heaps in Bytes. Dieser Wert bestimmt die anfängliche Arbeitsspeichermenge, die für den Heap committet wird. Der Wert wird auf ein Vielfaches der Systemseitengröße aufgerundet. Der Wert muss kleiner als dwMaximumSize sein.
Wenn dieser Parameter 0 ist, wird von der Funktion ein Commit für eine Seite ausgeführt. Verwenden Sie die GetSystemInfo-Funktion , um die Größe einer Seite auf dem Hostcomputer zu bestimmen.
[in] dwMaximumSize
Die maximale Größe des Heaps in Bytes. Die HeapCreate-Funktion rundet dwMaximumSize auf ein Vielfaches der Systemseitengröße auf und reserviert dann einen Block dieser Größe im virtuellen Adressraum des Prozesses für den Heap. Wenn Zuordnungsanforderungen, die von den Funktionen HeapAlloc oder HeapReAlloc gestellt werden, die von dwInitialSize angegebene Größe überschreiten, werden vom System zusätzliche Speicherseiten für den Heap bis zur maximalen Größe des Heaps committent.
Wenn dwMaximumSize nicht 0 ist, ist die Heapgröße festgelegt und kann nicht über die maximale Größe hinaus wachsen. Außerdem ist der größte Speicherblock, der über den Heap zugeordnet werden kann, etwas weniger als 512 KB für einen 32-Bit-Prozess und etwas weniger als 1.024 KB für einen 64-Bit-Prozess. Anforderungen zum Zuweisen größerer Blöcke schlagen fehl, auch wenn die maximale Größe des Heaps groß genug ist, um den Block zu enthalten.
Wenn dwMaximumSize 0 ist, kann der Heap größer werden. Die Größe des Heaps wird nur durch den verfügbaren Arbeitsspeicher begrenzt. Anforderungen zum Zuweisen von Speicherblöcken, die den Grenzwert für einen Heap mit fester Größe überschreiten, schlagen nicht automatisch fehl. Stattdessen ruft das System die VirtualAlloc-Funktion auf, um den Arbeitsspeicher abzurufen, der für große Blöcke benötigt wird. Anwendungen, die große Speicherblöcke zuordnen müssen, sollten dwMaximumSize auf 0 festlegen.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für den neu erstellten Heap.
Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
Die HeapCreate-Funktion erstellt ein privates Heapobjekt, aus dem der aufrufende Prozess Speicherblöcke mithilfe der HeapAlloc-Funktion zuordnen kann. Die anfängliche Größe bestimmt die Anzahl der zugesagten Seiten, die zunächst für den Heap zugewiesen werden. Die maximale Größe bestimmt die Gesamtzahl der reservierten Seiten. Diese Seiten erstellen einen Block im virtuellen Adressraum des Prozesses, in den der Heap hineinwachsen kann. Wenn Anforderungen von HeapAlloc die aktuelle Größe der committeten Seiten überschreiten, werden zusätzliche Seiten automatisch aus diesem reservierten Bereich committet, wenn der physische Speicher verfügbar ist.
Windows Server 2003 und Windows XP: Standardmäßig ist der neu erstellte private Heap ein Standardheap. Um den Heap mit geringer Fragmentierung zu aktivieren, rufen Sie die HeapSetInformation-Funktion mit einem Handle für den privaten Heap auf.
Auf den Arbeitsspeicher eines privaten Heapobjekts kann nur der Prozess zugreifen, der es erstellt hat. Wenn eine Dynamic Link Library (DLL) einen privaten Heap erstellt, wird der Heap im Adressraum des Prozesses erstellt, der die DLL aufruft, und nur für diesen Prozess kann darauf zugegriffen werden.
Das System verwendet Arbeitsspeicher aus dem privaten Heap, um Heapunterstützungsstrukturen zu speichern, sodass nicht die gesamte angegebene Heapgröße für den Prozess verfügbar ist. Wenn die HeapAlloc-Funktion beispielsweise 64 KB (K) von einem Heap mit einer maximalen Größe von 64 KB anfordert, schlägt die Anforderung möglicherweise aufgrund des Systemaufwands fehl.
Wenn HEAP_NO_SERIALIZE nicht angegeben ist (der einfache Standard), serialisiert der Heap den Zugriff innerhalb des aufrufenden Prozesses. Die Serialisierung stellt einen gegenseitigen Ausschluss sicher, wenn zwei oder mehr Threads gleichzeitig versuchen, 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. Die Funktionen HeapLock und HeapUnlock können verwendet werden, um einen serialisierten Heap zu blockieren und den Zugriff darauf zuzulassen.
Das Festlegen HEAP_NO_SERIALIZE 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 zu Einer Beschädigung des Heaps führen kann. Daher können HEAP_NO_SERIALIZE 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.
Wenn die Funktionen HeapLock und HeapUnlock auf einem Heap aufgerufen werden, der mit dem HEAP_NO_SERIALIZE-Flag erstellt wurde, sind die Ergebnisse nicht definiert.
Verwenden Sie die GetProcessHeap-Funktion , um ein Handle für den Standardheap für einen Prozess abzurufen. Verwenden Sie die GetProcessHeaps-Funktion , um Handles für die Standardheaps und privaten Heaps abzurufen, die für den aufrufenden Prozess aktiv sind.
Beispiele
Anforderungen
| 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 |