Función WaitOnAddress (synchapi.h)

  • Artículo

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.

Nota:WaitOnAddress se garantiza que se devuelva cuando se señala la dirección, pero también se puede devolver por otros motivos. Por este motivo, después de que WaitOnAddress devuelva el autor de la llamada debe comparar el nuevo valor con el valor original no deseado para confirmar que el valor ha cambiado realmente. Por ejemplo, las siguientes circunstancias pueden dar lugar a despertar el subproceso antes:
  • Condiciones de memoria baja
  • Se abandonó una reactivación anterior en la misma dirección
  • Ejecución de código en una compilación comprobada del sistema operativo
 

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

Requisito Value
Cliente mínimo compatible Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado synchapi.h (incluir Windows.h)
Library Synchronization.lib
Archivo DLL API-MS-Win-Core-Synch-l1-2-0.dll

Consulte también

WakeByAddressAll

WakeByAddressSingle

API de Vertdll disponibles en enclaves de VBS