WaitOnAddress-Funktion (synchapi.h)

Artikel
03/02/2024

Wartet, bis sich der Wert an der angegebenen Adresse ändert.

Syntax

BOOL WaitOnAddress(
  [in]           volatile VOID *Address,
  [in]           PVOID         CompareAddress,
  [in]           SIZE_T        AddressSize,
  [in, optional] DWORD         dwMilliseconds
);

Parameter

[in] Address

Die Adresse, auf die gewartet werden soll. Wenn sich der Wert unter Address vom Wert unter CompareAddress unterscheidet, wird die Funktion sofort zurückgegeben. Wenn die Werte identisch sind, gibt die Funktion erst zurück, wenn ein anderer Thread im gleichen Prozess durch Aufrufen von WakeByAddressSingle oder WakeByAddressAll signalisiert, dass sich der Wert unter Address geändert hat, oder das Timeout vergeht, je nachdem, was zuerst eintritt.

[in] CompareAddress

Ein Zeiger auf die Position des zuvor beobachteten Werts unter Adresse. Die Funktion gibt zurück, wenn sich der Wert unter Address vom Wert unter CompareAddress unterscheidet.

[in] AddressSize

Die Größe des Werts in Bytes. Dieser Parameter kann , 2, 4oder 8sein1.

[in, optional] dwMilliseconds

Die Anzahl von Millisekunden, die gewartet werden soll, bevor das Zeitüberschreitungsüberschreitung des Vorgangs auftritt. Wenn dieser Parameter INFINITE ist, wartet der Thread unbegrenzt.

Rückgabewert

TRUE , wenn die Wartezeit erfolgreich war. Wenn der Vorgang fehlschlägt, gibt die Funktion zurück FALSE. Wenn die Wartezeit fehlschlägt, rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Insbesondere wenn für den Vorgang ein Zeitüberschreitung auftritt, gibt GetLastErrorERROR_TIMEOUT zurück.

Hinweise

Microsoft Store-App-Entwickler müssen möglicherweise das synchronization.libWindows Software Development Kit (SDK) installieren.

Die WaitOnAddress-Funktion kann von einem Thread verwendet werden, um darauf zu warten, dass sich ein bestimmter Wert von einem unerwünschten Wert in einen anderen Wert ändert. WaitOnAddress ist effizienter als die Verwendung der Standbyfunktion innerhalb einer while Schleife, da WaitOnAddress den Threadplaner nicht beeinträchtigt. WaitOnAddress ist auch einfacher zu verwenden als ein Ereignisobjekt, da es nicht erforderlich ist, ein Ereignis zu erstellen und zu initialisieren und dann sicherzustellen, dass es ordnungsgemäß mit dem Wert synchronisiert wird. WaitOnAddress ist nicht von Bedingungen mit geringem Arbeitsspeicher betroffen, abgesehen davon, dass der Thread möglicherweise frühzeitig aktiviert wird, wie unten angegeben.

Jeder Thread innerhalb desselben Prozesses, der den Wert an der Adresse ändert, auf die Threads warten, sollte WakeByAddressSingle aufrufen, um einen einzelnen wartenden Thread zu reaktivieren, oder WakeByAddressAll , um alle wartenden Threads zu reaktivieren. Wenn WakeByAddressSingle aufgerufen wird, warten andere Wartethreads weiterhin.

Hinweis:WaitOnAddress wird garantiert zurückgegeben, wenn die Adresse signalisiert wird, aber es kann auch aus anderen Gründen zurückgegeben werden. Aus diesem Grund sollte der Aufrufer nach der Rückgabe von WaitOnAddress den neuen Wert mit dem ursprünglichen unerwünschten Wert vergleichen, um zu bestätigen, dass sich der Wert tatsächlich geändert hat. Die folgenden Umstände können beispielsweise dazu führen, dass der Thread frühzeitig aktiviert wird:

Geringe Arbeitsspeicherbedingungen
Eine vorherige Aktivierung für dieselbe Adresse wurde abgebrochen.
Ausführen von Code in einem überprüften Build des Betriebssystems

Beispiele

Im folgenden Beispiel wird gezeigt, wie WaitOnAddress verwendet wird.

ULONG g_TargetValue; // global, accessible to all threads
ULONG CapturedValue;
ULONG UndesiredValue;

UndesiredValue = 0;
CapturedValue = g_TargetValue;
while (CapturedValue == UndesiredValue) {
      WaitOnAddress(&g_TargetValue, &UndesiredValue, sizeof(ULONG), INFINITE);
      CapturedValue = g_TargetValue;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	synchapi.h (windows.h einschließen)
Bibliothek	Synchronization.lib
DLL	API-MS-Win-Core-Synch-l1-2-0.dll

Weitere Informationen

WakeByAddressAll

WakeByAddressSingle

In VBS-Enclaves verfügbare Vertdll-APIs

Freigeben über