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 SYNC è obbligatorio; per altre informazioni, vedere Sicurezza oggetti di sincronizzazione e diritti di accesso. Per un elenco dei tipi di oggetto i cui handle è possibile specificare, vedere la sezione Osservazioni.
[in] dwMilliseconds
Intervallo di timeout, in millisecondi. La funzione restituisce se l'intervallo viene trascorso, anche se lo stato dell'oggetto non è firmato e non viene eseguito alcun completamento o chiamata di routine asincrona (APC). Se dwMilliseconds è zero, la funzione verifica lo stato dell'oggetto, verifica le routine di completamento in coda o le API 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 o 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 alla 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 che appartiene all'oggetto mutex prima della chiusura del thread proprietario. La proprietà dell'oggetto mutex viene concessa al thread chiamante e il mutex è impostato su nonsignaled.
Se il mutex proteggeva le informazioni sullo stato persistenti, è necessario controllarlo per 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 su 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
- Process
- Semaphore
- Thread
- Timer attendebile
Un thread può usare la funzione SignalObjectAndWait per assicurarsi che un thread di lavoro si trova 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 proprio lavoro. Il thread esegue il codice, ad esempio quanto segue:
dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
if( WAIT_OBJECT_0 == dwRet)
SetEvent(hEventMoreWorkToDo);
Il thread di lavoro esegue il codice, ad esempio quanto segue:
dwRet = SignalObjectAndWait(hEventWorkerDone,
hEventMoreWorkToDo,
INFINITE,
FALSE);
Si noti che il "segnale" e "wait" non è garantito che venga eseguito come operazione atomica. I thread in esecuzione in altri processori possono osservare lo stato segnalato del primo oggetto prima che il thread che chiama SignalObjectAndWait inizi la sua attesa sul secondo oggetto.
Prestare attenzione estrema quando si usa SignalObjectAndWait e PulseEvent con Windows 7, poiché l'uso di queste API tra più thread può causare il deadlock di un'applicazione. I thread segnalati 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 di segnale dell'oggetto in attesa in tempo, causando un deadlock.
Prestare attenzione quando si usano le funzioni di attesa e il codice che crea direttamente o indirettamente 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 creano 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 versioni successive. Per altre informazioni, vedere Uso delle intestazioni di Windows.
Requisiti
| 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 (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |