Función WaitOnAddress (synchapi.h)

Espera a que cambie el valor en la dirección especificada.

Sintaxis

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

Parámetros

[in] Address

Dirección en la que se va a esperar. Si el valor de Address difiere del valor de CompareAddress, la función devuelve inmediatamente. Si los valores son los mismos, la función no devuelve hasta que otro subproceso del mismo proceso indica que el valor de Address ha cambiado llamando a WakeByAddressSingle o WakeByAddressAll o el tiempo de espera transcurrido, lo que ocurra primero.

[in] CompareAddress

Puntero a la ubicación del valor observado anteriormente en Address. La función devuelve cuando el valor de Address difiere del valor de CompareAddress.

[in] AddressSize

Tamaño del valor, en bytes. Este parámetro puede ser 1, 2, 4o 8.

[in, optional] dwMilliseconds

Número de milisegundos que se deben esperar antes de que se agote el tiempo de espera de la operación. Si este parámetro es INFINITE, el subproceso espera indefinidamente.

Valor devuelto

TRUE si la espera se realizó correctamente. Si se produce un error en la operación, la función devuelve FALSE. Si se produce un error en la espera, llame a GetLastError para obtener información de error extendida. En concreto, si se agota el tiempo de espera de la operación, GetLastError devuelve ERROR_TIMEOUT.

Comentarios

Es posible que los desarrolladores de aplicaciones de Microsoft Store necesiten obtener synchronization.lib mediante la instalación del Kit de desarrollo de software de Windows (SDK).

Un subproceso puede usar la función WaitOnAddress para esperar a que un valor determinado cambie de algún valor no deseado a cualquier otro valor. WaitOnAddress es más eficaz que usar la función Sleep dentro de un while bucle porque WaitOnAddress no interfiere con el programador de subprocesos. WaitOnAddress también es más sencillo de usar que un objeto de evento porque no es necesario crear e inicializar un evento y, a continuación, asegurarse de que se sincroniza correctamente con el valor. WaitOnAddress no se ve afectado por las condiciones de memoria baja, aparte de despertar el subproceso al principio, como se indica a continuación.

Cualquier subproceso dentro del mismo proceso que cambie el valor en la dirección en la que los subprocesos están esperando debe llamar a WakeByAddressSingle para reactivar un único subproceso en espera o WakeByAddressAll para reactivar todos los subprocesos en espera. Si se llama a WakeByAddressSingle , otros subprocesos en espera siguen esperando.

Ejemplos

En el ejemplo siguiente se muestra cómo usar 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;
}

Requisitos

Consulte también

WakeByAddressAll

WakeByAddressSingle

API de Vertdll disponibles en enclaves de VBS