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.
- 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 |