SetPriorityClass, fonction (processthreadsapi.h)

Article
03/04/2024

Définit la classe de priorité pour le processus spécifié. Cette valeur, associée à la valeur de priorité de chaque thread du processus, détermine le niveau de priorité de base de chaque thread.

Syntaxe

BOOL SetPriorityClass(
  [in] HANDLE hProcess,
  [in] DWORD  dwPriorityClass
);

Paramètres

[in] hProcess

Handle du processus.

Le handle doit avoir le droit d’accès PROCESS_SET_INFORMATION . Pour plus d’informations, consultez Droits d’accès et de sécurité des processus.

[in] dwPriorityClass

Classe de priorité pour le processus. Ce paramètre peut prendre les valeurs suivantes.

Priorité	Signification
ABOVE_NORMAL_PRIORITY_CLASS 0x00008000	Processus prioritaire au-dessus de NORMAL_PRIORITY_CLASS mais inférieur à HIGH_PRIORITY_CLASS.
BELOW_NORMAL_PRIORITY_CLASS 0x00004000	Processus prioritaire au-dessus de IDLE_PRIORITY_CLASS mais inférieur à NORMAL_PRIORITY_CLASS.
HIGH_PRIORITY_CLASS 0x00000080	Processus qui effectue des tâches critiques qui doivent être exécutées immédiatement. Les threads du processus prévalent sur les threads de processus de classe de priorités normale ou inactive. Par exemple, la liste des tâches doit répondre rapidement lorsqu’elle est appelée par l’utilisateur, quelle que soit la charge sur le système d’exploitation. Faites très attention lors de l’utilisation de la classe de priorité élevée, car une application de classe haute priorité peut utiliser presque tout le temps processeur disponible.
IDLE_PRIORITY_CLASS 0x00000040	Processus dont les threads s’exécutent uniquement lorsque le système est inactif. Les threads de tout processus s'exécutant dans une classe de priorités supérieure prévalent sur les threads du processus. Un écran de veille est un bon exemple. La classe de priorité inactive est héritée par les processus enfants.
NORMAL_PRIORITY_CLASS 0x00000020	Traiter sans besoin de planification particulière.
PROCESS_MODE_BACKGROUND_BEGIN 0x00100000	Commencez le mode de traitement en arrière-plan. Le système réduit les priorités de planification des ressources du processus (et de ses threads) afin qu’il puisse effectuer un travail en arrière-plan sans affecter de manière significative l’activité au premier plan. Cette valeur ne peut être spécifiée que si hProcess est un handle pour le processus actuel. La fonction échoue si le processus est déjà en mode de traitement en arrière-plan. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
PROCESS_MODE_BACKGROUND_END 0x00200000	Mettre fin au mode de traitement en arrière-plan. Le système restaure les priorités de planification des ressources du processus (et de ses threads) telles qu’elles étaient avant l’entrée du processus en mode de traitement en arrière-plan. Cette valeur ne peut être spécifiée que si hProcess est un handle pour le processus actuel. La fonction échoue si le processus n’est pas en mode de traitement en arrière-plan. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.
REALTIME_PRIORITY_CLASS 0x00000100	Processus ayant la priorité la plus élevée possible. Les threads du processus préemptent les threads de tous les autres processus, y compris les processus du système d’exploitation effectuant des tâches importantes. Par exemple, un processus en temps réel qui s’exécute pendant plus d’un intervalle très court peut empêcher le vidage des caches de disque ou empêcher la souris de répondre.

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.

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. 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. Pour plus d’informations, consultez Planification des priorités.

Les valeurs *_PRIORITY_CLASS affectent la priorité de planification du processeur du processus. Pour les processus 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 processus de priorité de processeur inactif peut facilement interférer avec la réactivité du système lorsqu’il utilise le disque et la mémoire. Les processus qui effectuent un travail en arrière-plan doivent utiliser les valeurs PROCESS_MODE_BACKGROUND_BEGIN et PROCESS_MODE_BACKGROUND_END pour ajuster leurs priorités de planification des ressources ; les processus qui interagissent avec l’utilisateur ne doivent pas utiliser PROCESS_MODE_BACKGROUND_BEGIN.

Si un processus est en mode de traitement en arrière-plan, les nouveaux threads qu’il crée sont également en mode de traitement en arrière-plan. 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é.

Chaque thread peut passer en mode de traitement en arrière-plan indépendamment à l’aide de SetThreadPriority. N’appelez pas SetPriorityClass pour passer en mode de traitement en arrière-plan après qu’un thread du processus a appelé SetThreadPriority pour passer en mode de traitement en arrière-plan. Une fois qu’un processus a terminé le mode de traitement en arrière-plan, il réinitialise tous les threads du processus ; Toutefois, il n’est pas possible pour le processus de savoir quels threads étaient déjà en mode de traitement en arrière-plan.

Exemples

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

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

int main( void )
{
   DWORD dwError, dwPriClass;

   if(!SetPriorityClass(GetCurrentProcess(), PROCESS_MODE_BACKGROUND_BEGIN))
   {
      dwError = GetLastError();
      if( ERROR_PROCESS_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 priority class

   dwPriClass = GetPriorityClass(GetCurrentProcess());

   _tprintf(TEXT("Current priority class is 0x%x\n"), dwPriClass);

   //
   // Perform background work
   //
   ;

   if(!SetPriorityClass(GetCurrentProcess(), PROCESS_MODE_BACKGROUND_END))
   {
      _tprintf(TEXT("Failed to end background mode (%d)\n"), GetLastError());
   }

Cleanup:
   // Clean up
   ;
return 0;
}

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	processthreadsapi.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll