Fonction SignalObjectAndWait (synchapi.h)
Signale un objet et attend un autre objet en tant qu’opération unique.
Syntaxe
DWORD SignalObjectAndWait(
[in] HANDLE hObjectToSignal,
[in] HANDLE hObjectToWaitOn,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Paramètres
[in] hObjectToSignal
Handle de l’objet à signaler. Cet objet peut être un sémaphore, un mutex ou un événement.
Si le handle est un sémaphore, le droit d’accès SEMAPHORE_MODIFY_STATE est requis. Si le handle est un événement, le droit d’accès EVENT_MODIFY_STATE est requis. Si le handle est un mutex et que l’appelant n’est pas propriétaire du mutex, la fonction échoue avec ERROR_NOT_OWNER.
[in] hObjectToWaitOn
Handle de l’objet à attendre. Le droit d’accès SYNCHRONIZE est requis ; Pour plus d’informations, consultez Synchronisation des droits d’accès et de sécurité des objets. Pour obtenir la liste des types d’objets dont vous pouvez spécifier les handles, consultez la section Remarques.
[in] dwMilliseconds
Intervalle de délai d’attente, en millisecondes. La fonction retourne si l’intervalle s’écoule, même si l’état de l’objet n’est pas signé et qu’aucun objet d’achèvement ou d’appel de procédure asynchrone (APC) n’est mis en file d’attente. Si dwMilliseconds est égal à zéro, la fonction teste l’état de l’objet, recherche les routines d’achèvement en file d’attente ou les API, puis retourne immédiatement. Si dwMilliseconds a la valeur INFINITE, l’intervalle de délai d’attente de la fonction ne s’écoule jamais.
[in] bAlertable
Si ce paramètre a la valeur TRUE, la fonction retourne lorsque le système met en file d’attente une routine d’achèvement d’E/S ou une fonction APC, et que le thread appelle la fonction. Si la valeur est FALSE, la fonction ne retourne pas et le thread n’appelle pas la routine d’achèvement ou la fonction APC.
Une routine d’achèvement est mise en file d’attente lorsque l’appel de fonction qui a mis en file d’attente l’APC est terminé. Cette fonction retourne et la routine d’achèvement est appelée uniquement si bAlertable a la valeur TRUE, et si le thread appelant est le thread qui a mis en file d’attente l’APC.
Valeur retournée
Si la fonction réussit, la valeur de retour indique l’événement qui a provoqué le retour de la fonction. Il peut avoir l’une des valeurs suivantes.
| Code/valeur de retour | Description |
|---|---|
|
L’objet spécifié est un objet mutex qui n’a pas été libéré par le thread qui possédait l’objet mutex avant la fin du thread propriétaire. La propriété de l’objet mutex est accordée au thread appelant, et le mutex est défini sur non signé.
Si le mutex protégeait les informations d’état persistantes, vous devez l’case activée à des fins de cohérence. |
|
L’attente a été terminée par un ou plusieurs appels de procédure asynchrone en mode utilisateur (APC) mis en file d’attente vers le thread. |
|
L’état de l’objet spécifié est signalé. |
|
L’intervalle de délai d’attente s’est écoulé et l’état de l’objet n’est pas signé. |
|
La fonction a échoué. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. |
Remarques
La fonction SignalObjectAndWait offre un moyen plus efficace de signaler un objet, puis d’attendre un autre par rapport à des appels de fonction distincts tels que SetEvent suivi de WaitForSingleObject.
La fonction SignalObjectAndWait peut attendre les objets suivants :
- Notification de modification
- Entrée de console
- Événement
- Notification de ressource mémoire
- Mutex
- Processus
- Semaphore
- Thread
- Minuteur d’attente
Un thread peut utiliser la fonction SignalObjectAndWait pour s’assurer qu’un thread de travail est dans un état d’attente avant de signaler un objet. Par exemple, un thread et un thread de travail peuvent utiliser des handles pour événementiser des objets afin de synchroniser leur travail. Le thread exécute du code tel que le suivant :
dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
if( WAIT_OBJECT_0 == dwRet)
SetEvent(hEventMoreWorkToDo);
Le thread de travail exécute le code suivant :
dwRet = SignalObjectAndWait(hEventWorkerDone,
hEventMoreWorkToDo,
INFINITE,
FALSE);
Notez que « signal » et « wait » ne sont pas garantis pour être exécutés en tant qu’opération atomique. Les threads qui s’exécutent sur d’autres processeurs peuvent observer l’état signalé du premier objet avant que le thread appelant SignalObjectAndWait commence son attente sur le deuxième objet.
Soyez extrêmement prudent lorsque vous utilisez SignalObjectAndWait et PulseEvent avec Windows 7, car l’utilisation de ces API entre plusieurs threads peut entraîner un blocage d’une application. Les threads signalés par SignalObjectAndWait appellent PulseEvent pour signaler l’objet en attente de l’appel SignalObjectAndWait . Dans certaines circonstances, l’appelant de SignalObjectAndWait ne peut pas recevoir l’état du signal de l’objet en attente dans le temps, ce qui provoque un blocage.
Soyez prudent lorsque vous utilisez les fonctions d’attente et le code qui créent directement ou indirectement des fenêtres. Si un thread crée des fenêtres, il doit traiter les messages. Les diffusions de messages sont envoyées à toutes les fenêtres du système. Un thread qui utilise une fonction d’attente sans intervalle de délai d’attente peut entraîner l’interblocage du système. Deux exemples de code qui créent indirectement des fenêtres sont DDE et COM CoInitialize. Par conséquent, si vous avez un thread qui crée des fenêtres, veillez à appeler SignalObjectAndWait à partir d’un autre thread. Si cela n’est pas possible, vous pouvez utiliser MsgWaitForMultipleObjects ou MsgWaitForMultipleObjectsEx, mais la fonctionnalité n’est pas équivalente.
Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0400 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau | applications UWP] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau | applications UWP] |
| Plateforme cible | Windows |
| En-tête | synchapi.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |