Funzione WaitOnAddress (synchapi.h)

Articolo
03/05/2024

Attende che il valore all'indirizzo specificato venga modificato.

Sintassi

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

Parametri

[in] Address

Indirizzo in cui attendere. Se il valore in Address è diverso dal valore in CompareAddress, la funzione restituisce immediatamente. Se i valori sono uguali, la funzione non restituisce fino a quando non viene restituito un altro thread nello stesso processo indica che il valore in Address è cambiato chiamando WakeByAddressSingle o WakeByAddressAll o il timeout trascorso.

[in] CompareAddress

Puntatore alla posizione del valore osservato in precedenza in Indirizzo. La funzione restituisce quando il valore in Address differisce dal valore in CompareAddress.

[in] AddressSize

Dimensioni del valore, in byte. Questo parametro può essere 1, , 42o 8.

[in, optional] dwMilliseconds

Numero di millisecondi da attendere prima del timeout dell'operazione. Se questo parametro è INFINITE, il thread attende in modo indefinito.

Valore restituito

TRUE se l'attesa ha avuto esito positivo. Se l'operazione ha esito negativo, la funzione restituisce FALSE. Se l'attesa ha esito negativo, chiamare GetLastError per ottenere informazioni di errore estese. In particolare, se l'operazione scade, GetLastError restituisce ERROR_TIMEOUT.

Commenti

Gli sviluppatori di app di Microsoft Store potrebbero dover ottenere synchronization.lib installando il Windows Software Development Kit (Windows SDK) (SDK).

La funzione WaitOnAddress può essere usata da un thread per attendere che un determinato valore venga modificato da un valore non indesiderato a qualsiasi altro valore. WaitOnAddress è più efficiente rispetto all'uso della funzione Sleep all'interno di un while ciclo perché WaitOnAddress non interferisce con l'utilità di pianificazione del thread. WaitOnAddress è anche più semplice da usare rispetto a un oggetto evento perché non è necessario creare e inizializzare un evento e quindi assicurarsi che sia sincronizzato correttamente con il valore. WaitOnAddress non è interessato da condizioni di memoria ridotta, oltre a svegliare il thread prima di quanto indicato di seguito.

Qualsiasi thread all'interno dello stesso processo che modifica il valore all'indirizzo in cui i thread sono in attesa deve chiamare WakeByAddressSingle per riattivare un singolo thread in attesa o WakeByAddressAll per riattivare tutti i thread in attesa. Se WakeByAddressSingle viene chiamato, altri thread in attesa continuano ad attendere.

Nota:WaitOnAddress è garantito di restituire quando l'indirizzo viene segnalato, ma è anche consentito restituire per altri motivi. Per questo motivo, dopo WaitOnAddress restituisce il chiamante deve confrontare il nuovo valore con il valore non indesiderato originale per confermare che il valore sia effettivamente cambiato. Ad esempio, le circostanze seguenti possono comportare la riattivazione anticipata del thread:

Condizioni di memoria ridotta
Una riattivazione precedente dello stesso indirizzo è stata abbandonata
Esecuzione del codice in una compilazione controllata del sistema operativo

Esempio

Nell'esempio seguente viene illustrato come usare 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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2012 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	synchapi.h (includere Windows.h)
Libreria	Sync.lib
DLL	API-MS-Win-Core-Synch-l1-2-0.dll

Vedi anche

WakeByAddressAll

WakeByAddressSingle

API Vertdll disponibili nelle enclave VBS

Share via