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
WAIT_ABANDONED
0x00000080L
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.

WAIT_IO_COMPLETION
0x00000C0L
L'attesa è stata terminata da una o più chiamate asincrone in modalità utente (APC) accodate al thread.
WAIT_OBJECT_0
0x00000000L
Lo stato dell'oggetto specificato viene segnalato.
WAIT_TIMEOUT
0x00000102L
Intervallo di timeout trascorso e lo stato dell'oggetto non è assegnato.
WAIT_FAILED
(DWORD)0xFFFFFFFF
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
Per altre informazioni, vedere Oggetti di sincronizzazione.

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

Vedere anche

MsgWaitForMultipleObjects

MsgWaitForMultipleObjectsEx

Funzioni di sincronizzazione

Funzioni di attesa