Condividi tramite


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

WAIT_IO_COMPLETION
0x00000C0L
L'attesa è stata terminata da una o più chiamate asincrone in modalità utente (APC) accodate al thread.
WAIT_OBJECT_0
0x0000000L
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 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
Per altre informazioni, vedere Oggetti di sincronizzazione.

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

Vedere anche

MsgWaitForMultipleObjects

MsgWaitForMultipleObjectsEx

Funzioni di sincronizzazione

Funzioni wait