VirtualAlloc2FromApp-Funktion (memoryapi.h)

Artikel
07/16/2024

Reserviert, commits oder ändert den Status eines Seitenbereichs im virtuellen Adressraum des aufrufenden Prozesses. Der von dieser Funktion zugewiesene Arbeitsspeicher wird automatisch auf Null initialisiert.

Mithilfe dieser Funktion können Sie: für neue Zuordnungen einen Bereich des virtuellen Adressraums und eine Leistungsbeschränkung für 2 Ausrichtung angeben; eine beliebige Anzahl erweiterter Parameter angeben; geben Sie einen bevorzugten NUMA-Knoten für den physischen Speicher als erweiterten Parameter an; und geben Sie einen Platzhaltervorgang an (insbesondere ersetzung).

Informationen zum Angeben des NUMA-Knotens finden Sie unter ExtendedParameters Parameter.

Syntax

PVOID VirtualAlloc2FromApp(
  [in, optional]      HANDLE                 Process,
  [in, optional]      PVOID                  BaseAddress,
  [in]                SIZE_T                 Size,
  [in]                ULONG                  AllocationType,
  [in]                ULONG                  PageProtection,
  [in, out, optional] MEM_EXTENDED_PARAMETER *ExtendedParameters,
  [in]                ULONG                  ParameterCount
);

Parameter

[in, optional] Process

Das Handle für einen Prozess. Die Funktion weist Speicher innerhalb des virtuellen Adressraums dieses Prozesses zu.

Das Handle muss über das PROCESS_VM_OPERATION Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Prozesssicherheits- und Zugriffsberechtigungen.

[in, optional] BaseAddress

Der Zeiger, der eine gewünschte Startadresse für den Bereich der Seiten angibt, die Sie zuordnen möchten.

Wenn BaseAddress-NULL-ist, bestimmt die Funktion, wo die Region zugeordnet werden soll.

Wenn BaseAddress- nicht NULL-ist, muss jede bereitgestellte MEM_ADDRESS_REQUIREMENTS Struktur aus allen Nullen bestehen, und die Basisadresse muss ein Vielfaches der Systemzuordnungs-Granularität sein. Um die Zuordnungs granularität zu bestimmen, verwenden Sie die GetSystemInfo--Funktion.

[in] Size

Die Größe des Speicherbereichs, der in Byte zugeordnet werden soll.

Die Größe muss immer ein Vielfaches der Seitengröße sein.

Wenn BaseAddress- nicht NULL-ist, weist die Funktion alle Seiten zu, die einen oder mehrere Bytes im Bereich von BaseAddressBaseAddress+Sizeenthalten. Dies bedeutet beispielsweise, dass ein 2-Byte-Bereich, der eine Seitengrenze überspannt, die funktion beide Seiten zuweist.

[in] AllocationType

Der Typ der Speicherzuweisung. Dieser Parameter muss einen der folgenden Werte enthalten.

Wert	Bedeutung
MEM_COMMIT 0x00001000	Weist Speichergebühren (von der Gesamtgröße des Arbeitsspeichers und der Auslagerungsdateien auf dem Datenträger) für die angegebenen reservierten Speicherseiten zu. Die Funktion garantiert außerdem, dass der Inhalt null ist, wenn der Aufrufer zu einem späteren Zeitpunkt auf den Speicher zugreift. Tatsächliche physische Seiten werden nur zugewiesen, wenn/bis tatsächlich auf die virtuellen Adressen zugegriffen wird. Rufen Sie Virtual2AllocFromApp mit `MEM_COMMIT \| MEM_RESERVE`auf, um Seiten in einem Schritt zu reservieren und zu übernehmen. Wenn Sie versuchen, einen bestimmten Adressbereich zu übernehmen, indem Sie MEM_COMMIT ohne MEM_RESERVE und eine nichtNULL-BaseAddress- angeben, tritt ein Fehler auf, es sei denn, der gesamte Bereich wurde bereits reserviert. Der resultierende Fehlercode ist ERROR_INVALID_ADDRESS. Ein Versuch, eine Seite zu übernehmen, die bereits zugesichert wurde, führt nicht dazu, dass die Funktion fehlschlägt. Dies bedeutet, dass Sie Seiten übernehmen können, ohne zuerst den aktuellen Verpflichtungsstatus jeder Seite zu bestimmen.
MEM_RESERVE 0x00002000	Reserviert einen Bereich des virtuellen Adressraums des Prozesses, ohne tatsächlichen physischen Speicher im Arbeitsspeicher oder in der Auslagerungsdatei auf dem Datenträger zuzuweisen. Sie können reservierte Seiten in nachfolgenden Aufrufen der Virtual2AllocFromApp--Funktion übernehmen. Rufen Sie Virtual2AllocFromApp mit MEM_COMMIT \| MEM_RESERVEauf, um Seiten in einem Schritt zu reservieren und zu übernehmen. Andere Speicherzuweisungsfunktionen wie malloc und LocalAlloc-können erst dann einen reservierten Speicherbereich verwenden, wenn sie freigegeben wird.
MEM_REPLACE_PLACEHOLDER 0x00004000	Ersetzt einen Platzhalter durch eine normale private Zuordnung. Es werden nur Daten-/Pf-gesicherte Abschnittsansichten unterstützt (keine Bilder, physischen Arbeitsspeicher usw.). Wenn Sie einen Platzhalter ersetzen, müssen BaseAddress- und Size exakt mit denen des Platzhalters übereinstimmen, und alle bereitgestellten MEM_ADDRESS_REQUIREMENTS Struktur müssen aus allen Nullen bestehen. Nachdem Sie einen Platzhalter durch eine private Zuordnung ersetzt haben, um diese Zuordnung wieder einem Platzhalter zu geben, lesen Sie den dwFreeType Parameter von VirtualFree und VirtualFreeEx. Ein Platzhalter ist ein Typ des reservierten Speicherbereichs.
MEM_RESERVE_PLACEHOLDER 0x00040000	Rufen Sie zum Erstellen eines Platzhalters VirtualAlloc2- mit `MEM_RESERVE \| MEM_RESERVE_PLACEHOLDER` und PageProtection- auf PAGE_NOACCESSfestgelegt. Informationen zum Freigeben/Teilen/Zusammenlegen eines Platzhalters finden Sie im dwFreeType Parameter von VirtualFree und VirtualFreeEx-. Ein Platzhalter ist ein Typ des reservierten Speicherbereichs.
MEM_RESET 0x00080000	Gibt an, dass Daten im durch BaseAddress- angegebenen Speicherbereich und Size nicht mehr von Interesse sind. Die Seiten sollten nicht aus der Auslagerungsdatei gelesen oder in die Auslagerungsdatei geschrieben werden. Der Speicherblock wird jedoch später wieder verwendet, sodass er nicht mehr ausgelassen werden sollte. Dieser Wert kann nicht mit einem anderen Wert verwendet werden. Die Verwendung dieses Werts garantiert nicht, dass der mit MEM_RESET betriebene Bereich Nullen enthält. Wenn der Bereich Nullen enthalten soll, dekommitieren Sie den Speicher, und übermitteln Sie ihn dann erneut. Wenn Sie MEM_RESETangeben, ignoriert die funktion Virtual2AllocFromApp den Wert Protection. Sie müssen jedoch weiterhin Protection auf einen gültigen Schutzwert festlegen, z. B. PAGE_NOACCESS. Virtual2AllocFromApp gibt einen Fehler zurück, wenn Sie MEM_RESET verwenden und der Speicherbereich einer Datei zugeordnet ist. Eine freigegebene Ansicht ist nur zulässig, wenn sie einer Auslagerungsdatei zugeordnet ist.
MEM_RESET_UNDO 0x1000000	MEM_RESET_UNDO sollte nur für einen Adressbereich aufgerufen werden, auf den MEM_RESET zuvor erfolgreich angewendet wurde. Es gibt an, dass die Daten im angegebenen Speicherbereich, der durch BaseAddress und Size für den Aufrufer von Interesse ist und versucht, die Auswirkungen von MEM_RESETrückgängig zu machen. Wenn die Funktion erfolgreich ist, bedeutet dies, dass alle Daten im angegebenen Adressbereich intakt sind. Wenn die Funktion fehlschlägt, wurden mindestens einige der Daten im Adressbereich durch Nullen ersetzt. Dieser Wert kann nicht mit einem anderen Wert verwendet werden. Wenn MEM_RESET_UNDO für einen Adressbereich aufgerufen wird, der zuvor nicht MEM_RESET wurde, ist das Verhalten nicht definiert. Wenn Sie MEM_RESETangeben, ignoriert die funktion Virtual2AllocFromApp den Wert Protection. Sie müssen jedoch weiterhin Protection auf einen gültigen Schutzwert festlegen, z. B. PAGE_NOACCESS.

Dieser Parameter kann auch die folgenden Werte wie angegeben angeben.

Wert	Bedeutung
MEM_LARGE_PAGES 0x20000000	Ordnet Arbeitsspeicher mithilfe Unterstützung für große Seitenzu. Die Größe und Ausrichtung müssen ein Vielfaches des Minimums für große Seiten sein. Verwenden Sie zum Abrufen dieses Werts die GetLargePageMinimum-Funktion. Wenn Sie diesen Wert angeben, müssen Sie auch MEM_RESERVE und MEM_COMMITangeben.
MEM_PHYSICAL 0x00400000	Reserviert einen Adressbereich, der verwendet werden kann, um Adressfenstererweiterungen (AWE)-Seiten zuzuordnen. Dieser Wert muss mit MEM_RESERVE und keinen anderen Werten verwendet werden.
MEM_TOP_DOWN 0x00100000	Weist Speicher mit der höchsten möglichen Adresse zu. Dies kann langsamer als die regulären Zuordnungen sein, insbesondere wenn viele Zuordnungen vorhanden sind.
MEM_WRITE_WATCH 0x00200000	Bewirkt, dass das System Seiten nachverfolgt, die in die zugeordnete Region geschrieben wurden. Wenn Sie diesen Wert angeben, müssen Sie auch MEM_RESERVEangeben. Rufen Sie die GetWriteWatch-Funktion auf, um die Adressen der Seiten abzurufen, die seit der Zuordnung der Region geschrieben wurden oder der Schreibverfolgungsstatus zurückgesetzt wurde. Rufen Sie GetWriteWatch- oder ResetWriteWatch-auf, um den Schreibstatus zurückzusetzen. Das Feature zum Nachverfolgen von Schreibvorgängen bleibt für den Speicherbereich aktiviert, bis die Region freigegeben wird.

[in] PageProtection

Der Speicherschutz für den Bereich der zuzuordnenden Seiten. Wenn die Seiten zugesichert werden, können Sie eine der Speicherschutzkonstantenangeben. Die folgenden Konstanten generieren einen Fehler:

PAGE_EXECUTE
PAGE_EXECUTE_READ
PAGE_EXECUTE_READWRITE
PAGE_EXECUTE_WRITECOPY

[in, out, optional] ExtendedParameters

Ein optionaler Zeiger auf einen oder mehrere erweiterte Parameter vom Typ MEM_EXTENDED_PARAMETER. Jeder dieser erweiterten Parameterwerte kann selbst ein Type-Feld von entweder MemExtendedParameterAddressRequirements oder MemExtendedParameterNumaNodehaben. Wenn kein MemExtendedParameterNumaNode erweiterter Parameter bereitgestellt wird, ist das Verhalten identisch mit den Funktionen VirtualAlloc/MapViewOfFile (d. a. der bevorzugte NUMA-Knoten für die physischen Seiten wird basierend auf dem idealen Prozessor des Threads bestimmt, der zuerst auf den Speicher zugreift).

[in] ParameterCount

Die Anzahl der erweiterten Parameter, auf die durch ExtendedParametersverwiesen wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Basisadresse des zugeordneten Seitenbereichs.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Diese API unterstützt leistungsstarke Spiele und Serveranwendungen, die spezielle Anforderungen hinsichtlich der Verwaltung des virtuellen Adressraums haben. Beispiel: Zuordnen des Speichers über einem zuvor reservierten Bereich; Dies ist nützlich für die Implementierung eines automatisch umbrochenen Ringpuffers. Und das Zuordnen des Speichers mit einer bestimmten Ausrichtung; Um ihre Anwendung z. B. das Commit großer/riesiger seitenzuordnunger Regionen bei Bedarf zu ermöglichen.

Sie können Virtual2AllocFromApp- aus Windows Store-Apps mit Just-in-Time-Funktionen (JIT) aufrufen, um JIT-Funktionen zu verwenden. Die App muss die funktion CodeGeneration in der App-Manifestdatei enthalten, um JIT-Funktionen zu verwenden.

Jede Seite verfügt über einen zugeordneten Seitenzustand. Die funktion Virtual2AllocFromApp kann die folgenden Vorgänge ausführen:

Übernehmen eines Bereichs reservierter Seiten
Reservieren einer Region mit kostenlosen Seiten
Gleichzeitiges Reservieren und Übernehmen einer Region kostenloser Seiten

Virtual2AllocFromApp kann keine reservierte Seite reservieren. Sie kann eine Seite übernehmen, die bereits zugesichert ist. Dies bedeutet, dass Sie einen Seitenbereich übernehmen können, unabhängig davon, ob sie bereits zugesichert wurden, und die Funktion schlägt nicht fehl.

Sie können Virtual2AllocFromApp verwenden, um einen Seitenblock zu reservieren und dann zusätzliche Aufrufe an Virtual2AllocFromApp, um einzelne Seiten aus dem reservierten Block zu übernehmen. Dadurch kann ein Prozess einen Bereich seines virtuellen Adressraums reservieren, ohne physischen Speicher zu verbrauchen, bis er benötigt wird.

Wenn der parameter BaseAddress nicht NULL-ist, verwendet die Funktion die BaseAddress- und Size Parameter, um den bereich der zuzuordnenden Seiten zu berechnen. Der aktuelle Zustand des gesamten Seitenbereichs muss mit dem typ der durch den parameter AllocationType angegebenen Zuordnung kompatibel sein. Andernfalls schlägt die Funktion fehl, und keiner der Seiten wird zugewiesen. Diese Kompatibilitätsanforderung schließt das Commit einer bereits zugesicherten Seite nicht aus, wie zuvor erwähnt.

Virtual2AllocFromApp die Erstellung von ausführbaren Seiten nicht zulässt.

Die Virtual2AllocFromApp--Funktion kann verwendet werden, um eine Adressfenstererweiterungen (AWE)-Bereich des Arbeitsspeichers innerhalb des virtuellen Adressraums eines angegebenen Prozesses zu reservieren. Dieser Speicherbereich kann dann verwendet werden, um physische Seiten nach Bedarf der Anwendung in und außerhalb des virtuellen Arbeitsspeichers zuzuordnen. Die werte MEM_PHYSICAL und MEM_RESERVE müssen im parameter AllocationType festgelegt werden. Der wert MEM_COMMIT darf nicht festgelegt werden. Der Seitenschutz muss auf PAGE_READWRITEfestgelegt werden.

Die funktion VirtualFree kann eine zugesicherte Seite aufheben, den Speicher der Seite freigeben oder gleichzeitig eine zugesicherte Seite aufheben und freigeben. Sie kann auch eine reservierte Seite freigeben, wodurch sie eine kostenlose Seite wird.

Beim Erstellen einer Region, die ausführbar ist, trägt das aufrufende Programm die Verantwortung für die Sicherstellung der Cachekohärenz über einen entsprechenden Aufruf von FlushInstructionCache, nachdem der Code eingerichtet wurde. Andernfalls kann der Versuch, Code aus dem neu ausführbaren Bereich auszuführen, zu unvorhersehbaren Ergebnissen führen.

Beispiele

Codebeispiele finden Sie unter Virtual2Alloc.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 10 [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2016 [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	memoryapi.h (include Windows.h)
Library	WindowsApp.lib
DLL-	Kernel32.dll