SetThreadPriority, fonction (processthreadsapi.h)

Définit la valeur de priorité pour le thread spécifié. Cette valeur, ainsi que la classe de priorité du processus du thread, déterminent le niveau de priorité de base du thread.

Syntaxe

BOOL SetThreadPriority(
  [in] HANDLE hThread,
  [in] int    nPriority
);

Paramètres

[in] hThread

Handle du thread dont la valeur de priorité doit être définie.

Le handle doit avoir le droit d’accès THREAD_SET_INFORMATION ou THREAD_SET_LIMITED_INFORMATION . Pour plus d’informations, consultez Sécurité des threads et droits d’accès. Windows Server 2003 : Le handle doit avoir le droit d’accès THREAD_SET_INFORMATION .

[in] nPriority

Valeur de priorité pour le thread. Ce paramètre peut prendre les valeurs suivantes.

Si le thread a la classe de base REALTIME_PRIORITY_CLASS , ce paramètre peut également être -7, -6, -5, -4, -3, 3, 4, 5 ou 6. Pour plus d’informations, consultez Planification des priorités.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Windows Phone 8.1 : Windows Phone applications du Store peuvent appeler cette fonction, mais elle n’a aucun effet. La fonction retourne une valeur différente de zéro indiquant la réussite.

Remarques

Chaque thread a un niveau de priorité de base déterminé par la valeur de priorité du thread et la classe de priorité de son processus. Le système utilise le niveau de priorité de base de tous les threads exécutables pour déterminer quel thread obtient la tranche de temps processeur suivante. Les threads sont planifiés en tourniquet (round robin) à chaque niveau de priorité, et c’est seulement lorsqu’il n’y a pas de threads exécutables à un niveau supérieur que la planification des threads à un niveau inférieur a lieu.

La fonction SetThreadPriority permet de définir le niveau de priorité de base d’un thread par rapport à la classe de priorité de son processus. Par exemple, en spécifiant THREAD_PRIORITY_HIGHEST dans un appel à SetThreadPriority pour un thread d’un processus IDLE_PRIORITY_CLASS définit le niveau de priorité de base du thread sur 6. Pour obtenir un tableau montrant les niveaux de priorité de base pour chaque combinaison de classe de priorité et de valeur de priorité de thread, consultez Priorités de planification.

Pour les processus IDLE_PRIORITY_CLASS, BELOW_NORMAL_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, ABOVE_NORMAL_PRIORITY_CLASS et HIGH_PRIORITY_CLASS , le système augmente dynamiquement le niveau de priorité de base d’un thread lorsque des événements importants pour le thread se produisent. REALTIME_PRIORITY_CLASS processus ne reçoivent pas d’améliorations dynamiques.

Tous les threads commencent initialement à THREAD_PRIORITY_NORMAL. Utilisez les fonctions GetPriorityClass et SetPriorityClass pour obtenir et définir la classe de priorité d’un processus. Utilisez la fonction GetThreadPriority pour obtenir la valeur de priorité d’un thread.

Utilisez la classe de priorité d’un processus pour faire la différence entre les applications qui ont un temps critique et celles qui ont des exigences de planification normales ou inférieures à la normale. Utilisez des valeurs de priorité de thread pour différencier les priorités relatives des tâches d’un processus. Par exemple, un thread qui gère l’entrée d’une fenêtre peut avoir un niveau de priorité plus élevé qu’un thread qui effectue des calculs intensifs pour le processeur.

Lors de la manipulation des priorités, veillez à ce qu’un thread de priorité élevée ne consomme pas tout le temps processeur disponible. Un thread dont le niveau de priorité de base est supérieur à 11 interfère avec le fonctionnement normal du système d’exploitation. L’utilisation de REALTIME_PRIORITY_CLASS peut entraîner le vidage des caches de disque, l’arrêt de la réponse de la souris, etc.

Les valeurs THREAD_PRIORITY_* affectent la priorité de planification du processeur du thread. Pour les threads qui effectuent des tâches en arrière-plan telles que les E/S de fichiers, les E/S réseau ou le traitement des données, il ne suffit pas d’ajuster la priorité de planification du processeur ; même un thread de priorité processeur inactif peut facilement interférer avec la réactivité du système lorsqu’il utilise le disque et la mémoire. Les threads qui effectuent un travail en arrière-plan doivent utiliser les valeurs THREAD_MODE_BACKGROUND_BEGIN et THREAD_MODE_BACKGROUND_END pour ajuster leurs priorités de planification des ressources ; Les threads qui interagissent avec l’utilisateur ne doivent pas utiliser THREAD_MODE_BACKGROUND_BEGIN.

Lorsqu’un thread est en mode de traitement en arrière-plan, il doit réduire le partage des ressources telles que les sections critiques, les tas et les handles avec d’autres threads dans le processus, sinon des inversions de priorité peuvent se produire. Si des threads s’exécutent à priorité élevée, un thread en mode de traitement en arrière-plan peut ne pas être planifié rapidement, mais il ne sera jamais affamé.

Windows Server 2008 et Windows Vista : Pendant le démarrage du système, la fonction SetThreadPriority retourne une valeur de retour de réussite, mais ne modifie pas la priorité du thread pour les applications démarrées à partir du dossier démarrage du système ou répertoriées dans la clé de Registre HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run . Ces applications s’exécutent à priorité réduite pendant une courte période (environ 60 secondes) pour rendre le système plus réactif aux actions de l’utilisateur au démarrage.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store.

Windows Phone 8.1 :Windows Phone les applications du Store peuvent appeler cette fonction, mais elle n’a aucun effet.

Exemples

L’exemple suivant illustre l’utilisation du mode d’arrière-plan de thread.

#include <windows.h>
#include <tchar.h>

int main( void )
{
   DWORD dwError, dwThreadPri;

   if(!SetThreadPriority(GetCurrentThread(), THREAD_MODE_BACKGROUND_BEGIN))
   {
      dwError = GetLastError();
      if( ERROR_THREAD_MODE_ALREADY_BACKGROUND == dwError)
         _tprintf(TEXT("Already in background mode\n"));
      else _tprintf(TEXT("Failed to enter background mode (%d)\n"), dwError);
      goto Cleanup;
   } 

   // Display thread priority

   dwThreadPri = GetThreadPriority(GetCurrentThread());

   _tprintf(TEXT("Current thread priority is 0x%x\n"), dwThreadPri);

   //
   // Perform background work
   //
   ;

   if(!SetThreadPriority(GetCurrentThread(), THREAD_MODE_BACKGROUND_END))
   {
      _tprintf(TEXT("Failed to end background mode (%d)\n"), GetLastError());
   }

Cleanup:
   // Clean up
   ;
return 0;
}

Configuration requise

Voir aussi

GetPriorityClass

GetThreadPriority

Fonctions de processus et de thread

Priorités de planification

SetPriorityClass

Threads