Funzione SignalObjectAndWait (synchapi.h)
Segnala un oggetto e attende su un altro oggetto come singola operazione.
Sintassi
DWORD SignalObjectAndWait(
[in] HANDLE hObjectToSignal,
[in] HANDLE hObjectToWaitOn,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parametri
[in] hObjectToSignal
Handle per l'oggetto da segnalare. Questo oggetto può essere un semaforo, un mutex o un evento.
Se l'handle è un semaforo, è necessario il diritto di accesso SEMAPHORE_MODIFY_STATE . Se l'handle è un evento, è necessario il diritto di accesso EVENT_MODIFY_STATE . Se l'handle è un mutex e il chiamante non possiede il mutex, la funzione ha esito negativo con ERROR_NOT_OWNER.
[in] hObjectToWaitOn
Handle per l'oggetto da attendere. Il diritto di accesso SYNCHRONIZE è obbligatorio; per altre informazioni, vedere Diritti di accesso e sicurezza degli oggetti di sincronizzazione. Per un elenco dei tipi di oggetto i cui handle è possibile specificare, vedere la sezione Osservazioni.
[in] dwMilliseconds
Intervallo di timeout, espresso in millisecondi. La funzione restituisce se l'intervallo è trascorso, anche se lo stato dell'oggetto è non firmato e non viene accodato alcun oggetto di completamento o chiamata asincrona di routine (APC). Se dwMilliseconds è zero, la funzione verifica lo stato dell'oggetto, verifica la presenza di routine o APC di completamento in coda e restituisce immediatamente. Se dwMilliseconds è INFINITE, l'intervallo di timeout della funzione non scade mai.
[in] bAlertable
Se questo parametro è TRUE, la funzione restituisce quando il sistema accoda una routine di completamento I/O o una funzione APC e il thread chiama la funzione. Se FALSE, la funzione non restituisce e il thread non chiama la routine di completamento o la funzione APC.
Una routine di completamento viene accodata quando la chiamata di funzione che ha accodato l'APC è stata completata. Questa funzione restituisce e la routine di completamento viene chiamata solo se bAlertable è TRUE e il thread chiamante è il thread che ha accodato l'APC.
Valore restituito
Se la funzione ha esito positivo, il valore restituito indica l'evento che ha causato la restituzione della funzione. Può essere uno dei valori seguenti.
| Codice/valore restituito | Descrizione |
|---|---|
|
L'oggetto specificato è un oggetto mutex che non è stato rilasciato dal thread di proprietà dell'oggetto mutex prima che il thread proprietario venga terminato. La proprietà dell'oggetto mutex viene concessa al thread chiamante e il mutex è impostato su non firmato.
Se il mutex proteggeva le informazioni sullo stato persistente, è necessario verificarne la coerenza. |
|
L'attesa è stata terminata da una o più chiamate asincrone in modalità utente (APC) accodate al thread. |
|
Lo stato dell'oggetto specificato viene segnalato. |
|
Intervallo di timeout trascorso e lo stato dell'oggetto non è assegnato. |
|
La funzione non è riuscita. Per informazioni dettagliate sull'errore, chiamare GetLastError. |
Commenti
La funzione SignalObjectAndWait offre un modo più efficiente per segnalare un oggetto e quindi attendere un altro rispetto a chiamate di funzione separate, ad esempio SetEvent seguito da WaitForSingleObject.
La funzione SignalObjectAndWait può attendere gli oggetti seguenti:
- Notifica di modifica
- Input della console
- Evento
- Notifica delle risorse di memoria
- Mutex
- Processo
- Semaphore
- Thread
- Timer waitable
Un thread può usare la funzione SignalObjectAndWait per assicurarsi che un thread di lavoro sia in uno stato di attesa prima di segnalare un oggetto. Ad esempio, un thread e un thread di lavoro possono usare handle per gli oggetti evento per sincronizzare il lavoro. Il thread esegue codice come il seguente:
dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
if( WAIT_OBJECT_0 == dwRet)
SetEvent(hEventMoreWorkToDo);
Il thread di lavoro esegue codice come il seguente:
dwRet = SignalObjectAndWait(hEventWorkerDone,
hEventMoreWorkToDo,
INFINITE,
FALSE);
Si noti che non è garantito che "signal" e "wait" vengano eseguiti come operazione atomica. I thread in esecuzione su altri processori possono osservare lo stato segnalato del primo oggetto prima che il thread che chiama SignalObjectAndWait inizi l'attesa sul secondo oggetto.
Prestare particolare attenzione quando si usa SignalObjectAndWait e PulseEvent con Windows 7, poiché l'uso di queste API tra più thread può causare un deadlock di un'applicazione. I thread che vengono segnalato da SignalObjectAndWait chiama PulseEvent per segnalare l'oggetto in attesa della chiamata SignalObjectAndWait . In alcune circostanze, il chiamante di SignalObjectAndWait non può ricevere lo stato del segnale dell'oggetto in attesa nel tempo, causando un deadlock.
Prestare attenzione quando si usano le funzioni di attesa e il codice che crea direttamente o indirettamente le finestre. Se un thread crea finestre, deve elaborare i messaggi. Le trasmissioni dei messaggi vengono inviate a tutte le finestre del sistema. Un thread che usa una funzione di attesa senza intervallo di timeout può causare il deadlock del sistema. Due esempi di codice che crea indirettamente finestre sono DDE e COM CoInitialize. Pertanto, se si dispone di un thread che crea finestre, assicurarsi di chiamare SignalObjectAndWait da un thread diverso. Se non è possibile, è possibile usare MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, ma la funzionalità non è equivalente.
Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0400 o versione successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | synchapi.h (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |