Fonction SleepEx (synchapi.h)

Article
08/26/2023

Suspend le thread actuel jusqu’à ce que la condition spécifiée soit remplie. L’exécution reprend lorsque l’une des opérations suivantes se produit :

Une fonction de rappel d’achèvement des E/S est appelée.
Un appel de procédure asynchrone (APC) est mis en file d’attente vers le thread.
L’intervalle de délai d’attente s’écoule.

Syntaxe

DWORD SleepEx(
  [in] DWORD dwMilliseconds,
  [in] BOOL  bAlertable
);

Paramètres

[in] dwMilliseconds

Intervalle de temps pendant lequel l’exécution doit être suspendue, en millisecondes.

La valeur zéro fait que le thread abandonne le reste de sa tranche de temps à tout autre thread prêt à s’exécuter. S’il n’y a pas d’autres threads prêts à être exécutés, la fonction retourne immédiatement et le thread poursuit l’exécution. Windows XP : La valeur zéro fait que le thread abandonne le reste de sa tranche de temps à tout autre thread de priorité égale prêt à être exécuté. S’il n’y a pas d’autres threads de priorité égale prêts à être exécutés, la fonction retourne immédiatement et le thread poursuit l’exécution. Ce comportement a changé à partir de Windows Server 2003.

La valeur INFINITE indique que la suspension ne doit pas expirer.

[in] bAlertable

Si ce paramètre a la valeur FALSE, la fonction ne retourne pas tant que le délai d’attente n’est pas écoulé. Si un rappel d’achèvement d’E/S se produit, la fonction ne retourne pas immédiatement et la fonction d’achèvement d’E/S n’est pas exécutée. Si un APC est mis en file d’attente vers le thread, la fonction ne retourne pas immédiatement et la fonction APC n’est pas exécutée.

Si le paramètre a la valeur TRUE et que le thread qui a appelé cette fonction est le même thread que celui qui a appelé la fonction d’E/S étendue (ReadFileEx ou WriteFileEx), la fonction retourne lorsque le délai d’attente s’est écoulé ou lorsqu’une fonction de rappel d’achèvement d’E/S se produit. Si un rappel d’achèvement d’E/S se produit, la fonction d’achèvement d’E/S est appelée. Si un APC est mis en file d’attente vers le thread (QueueUserAPC), la fonction retourne lorsque le délai d’attente s’est écoulé ou lorsque la fonction APC est appelée.

Valeur retournée

La valeur de retour est zéro si l’intervalle de temps spécifié a expiré.

La valeur de retour est WAIT_IO_COMPLETION si la fonction est retournée en raison d’une ou plusieurs fonctions de rappel d’achèvement d’E/S. Cela ne peut se produire que si bAlertable a la valeur TRUE et si le thread qui a appelé la fonction SleepEx est le même thread que celui qui a appelé la fonction d’E/S étendue.

Remarques

Cette fonction fait qu’un thread abandonne le reste de sa tranche de temps et devient inexécutable pendant un intervalle basé sur la valeur de dwMilliseconds. Une fois l’intervalle de veille passé, le thread est prêt à s’exécuter. Notez qu’il n’est pas garanti qu’un thread prêt s’exécute immédiatement. Par conséquent, le thread ne s’exécutera qu’après un certain temps arbitraire après l’expiration de l’intervalle de veille, en fonction de la fréquence de « graduation » du système et du facteur de charge d’autres processus. L’horloge système « tourne » à un rythme constant. Pour augmenter la précision de l’intervalle de veille, appelez la fonction timeGetDevCaps pour déterminer la résolution minimale du minuteur prise en charge et la fonction timeBeginPeriod pour définir la résolution du minuteur à son minimum. Soyez prudent lorsque vous appelez timeBeginPeriod, car les appels fréquents peuvent affecter considérablement l’horloge système, l’utilisation de l’alimentation du système et le planificateur. Si vous appelez timeBeginPeriod, appelez-la une fois plus tôt dans l’application et veillez à appeler la fonction timeEndPeriod à la toute fin de l’application. Si vous spécifiez 0 milliseconde, le thread abandonne le reste de sa tranche de temps, mais reste prêt. Pour plus d’informations, consultez Planification des priorités.

Cette fonction peut être utilisée avec les fonctions ReadFileEx ou WriteFileEx pour suspendre un thread jusqu’à ce qu’une opération d’E/S soit terminée. Ces fonctions spécifient une routine d’achèvement qui doit être exécutée une fois l’opération d’E/S terminée. Pour que la routine d’achèvement soit exécutée, le thread qui a appelé la fonction d’E/S doit être dans un état d’attente pouvant être alerté lorsque la fonction de rappel d’achèvement se produit. Un thread passe à un état d’attente pouvant être alerté en appelant SleepEx, MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx ou WaitForMultipleObjectsEx, avec le paramètre bAlertable de la fonction défini sur TRUE.

Soyez prudent lorsque vous utilisez SleepEx dans les scénarios suivants :

Code qui crée directement ou indirectement des fenêtres (par exemple, DDE et COM CoInitialize). 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. Si vous avez un thread qui utilise SleepEx avec un délai infini, le système se bloquera.
Threads qui sont sous contrôle d’accès concurrentiel. Par exemple, un port d’achèvement d’E/S ou un pool de threads limite le nombre de threads associés pouvant s’exécuter. Si le nombre maximal de threads est déjà en cours d’exécution, aucun thread associé supplémentaire ne peut s’exécuter tant qu’un thread en cours d’exécution n’est pas terminé. Si un thread utilise SleepEx avec un intervalle de zéro pour attendre que l’un des threads associés supplémentaires effectue un travail, le processus peut se bloquer.

Pour ces scénarios, utilisez MsgWaitForMultipleObjects ou MsgWaitForMultipleObjectsEx, plutôt que SleepEx.

Windows Phone 8.1 : cette fonction est prise en charge pour les applications Windows Phone Store sur Windows Phone 8.1 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise


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 sur Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib; WindowsPhoneCore.lib sur Windows Phone 8.1
DLL	KernelBase.dll sur Windows Phone 8.1; Kernel32.dll