Fonction WaitOnAddress (synchapi.h)

Article
03/04/2024

Attend que la valeur à l’adresse spécifiée change.

Syntaxe

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

Paramètres

[in] Address

Adresse sur laquelle attendre. Si la valeur dans Address diffère de la valeur dans CompareAddress, la fonction retourne immédiatement. Si les valeurs sont identiques, la fonction ne retourne pas tant qu’un autre thread dans le même processus ne signale pas que la valeur sur Address a changé en appelant WakeByAddressSingle ou WakeByAddressAll ou que le délai d’expiration s’écoule, selon la première éventualité.

[in] CompareAddress

Pointeur vers l’emplacement de la valeur observée précédemment dans Adresse. La fonction retourne lorsque la valeur dans Address diffère de la valeur dans CompareAddress.

[in] AddressSize

Taille de la valeur, en octets. Ce paramètre peut être 1, 2, 4ou 8.

[in, optional] dwMilliseconds

Nombre de millisecondes à attendre avant l’expiration de l’opération. Si ce paramètre est INFINITE, le thread attend indéfiniment.

Valeur retournée

TRUE si l’attente a réussi. Si l’opération échoue, la fonction retourne FALSE. Si l’attente échoue, appelez GetLastError pour obtenir des informations d’erreur étendues. En particulier, si l’opération expire, GetLastError retourne ERROR_TIMEOUT.

Remarques

Les développeurs d’applications du Microsoft Store peuvent avoir besoin d’obtenir synchronization.lib en installant le Kit de développement logiciel Windows (Kit SDK Windows) (SDK) .

La fonction WaitOnAddress peut être utilisée par un thread pour attendre qu’une valeur particulière passe d’une valeur non souhaitée à une autre valeur. WaitOnAddress est plus efficace que l’utilisation de la fonction Veille à l’intérieur d’une while boucle, car WaitOnAddress n’interfère pas avec le planificateur de threads. WaitOnAddress est également plus simple à utiliser qu’un objet d’événement, car il n’est pas nécessaire de créer et d’initialiser un événement, puis de s’assurer qu’il est correctement synchronisé avec la valeur. WaitOnAddress n’est pas affecté par des conditions de mémoire insuffisante, autres que le réveil potentiel du thread tôt, comme indiqué ci-dessous.

Tout thread dans le même processus qui modifie la valeur à l’adresse sur laquelle les threads sont en attente doit appeler WakeByAddressSingle pour réveiller un seul thread en attente ou WakeByAddressAll pour réveiller tous les threads en attente. Si WakeByAddressSingle est appelé, d’autres threads en attente continuent d’attendre.

Remarque : Le retour de WaitOnAddress est garanti lorsque l’adresse est signalée, mais elle est également autorisée à retourner pour d’autres raisons. Pour cette raison, une fois que WaitOnAddress retourne, l’appelant doit comparer la nouvelle valeur à la valeur non souhaitée d’origine pour confirmer que la valeur a bien changé. Par exemple, les circonstances suivantes peuvent entraîner le réveil précoce du thread :

Conditions de mémoire faible
Un wake précédent sur la même adresse a été abandonné
Exécution de code sur une build vérifiée du système d’exploitation

Exemples

L’exemple suivant montre comment utiliser WaitOnAddress.

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;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	synchapi.h (inclure Windows.h)
Bibliothèque	Synchronization.lib
DLL	API-MS-Win-Core-Synch-l1-2-0.dll

Voir aussi

WakeByAddressAll

WakeByAddressSingle

API Vertdll disponibles dans les enclaves VBS

Partager via