SetPriorityClass-Funktion (processthreadsapi.h)

Artikel
08/25/2023

Legt die Prioritätsklasse für den angegebenen Prozess fest. Dieser Wert bestimmt zusammen mit dem Prioritätswert jedes Threads des Prozesses die Basisprioritätsebene jedes Threads.

Syntax

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

Parameter

[in] hProcess

Ein Handle für den Prozess.

Das Handle muss über das Zugriffsrecht PROCESS_SET_INFORMATION verfügen. Weitere Informationen finden Sie unter Prozesssicherheit und Zugriffsrechte.

[in] dwPriorityClass

Die Prioritätsklasse für den Prozess. Dieser Parameter kann einen der folgenden Werte annehmen.

Priority	Bedeutung
ABOVE_NORMAL_PRIORITY_CLASS 0x00008000	Prozess mit Priorität oberhalb NORMAL_PRIORITY_CLASS , aber unterhalb HIGH_PRIORITY_CLASS.
BELOW_NORMAL_PRIORITY_CLASS 0x00004000	Prozess, der über IDLE_PRIORITY_CLASS , aber unterhalb NORMAL_PRIORITY_CLASS Priorität hat.
HIGH_PRIORITY_CLASS 0x00000080	Prozess, der zeitkritische Aufgaben ausführt, die sofort ausgeführt werden müssen. Die Threads des Prozesses haben Vorrang vor den Threads von Prozessen in den Prioritätsklassen mit normaler oder Leerlaufpriorität. Ein Beispiel ist die Aufgabenliste, die schnell reagieren muss, wenn sie vom Benutzer aufgerufen wird, unabhängig von der Auslastung des Betriebssystems. Verwenden Sie bei der Verwendung der Klasse mit hoher Priorität äußerste Sorgfalt, da eine Klasse mit hoher Priorität fast die gesamte verfügbare CPU-Zeit nutzen kann.
IDLE_PRIORITY_CLASS 0x00000040	Prozess, dessen Threads nur ausgeführt werden, wenn sich das System im Leerlauf befindet. Vor den Threads dieses Prozesses haben die Threads eines beliebigen Prozesses Vorrang, der mit einer höheren Prioritätsklasse ausgeführt wird. Ein Beispiel ist ein Bildschirmschoner. Die Leerlaufprioritätsklasse wird von untergeordneten Prozessen geerbt.
NORMAL_PRIORITY_CLASS 0x00000020	Prozess ohne besondere Planungsanforderungen.
PROCESS_MODE_BACKGROUND_BEGIN 0x00100000	Starten Sie den Hintergrundverarbeitungsmodus. Das System senkt die Ressourcenplanungsprioritäten des Prozesses (und seiner Threads), sodass hintergrundarbeiten ausgeführt werden können, ohne die Aktivität im Vordergrund erheblich zu beeinträchtigen. Dieser Wert kann nur angegeben werden, wenn hProcess ein Handle für den aktuellen Prozess ist. Die Funktion schlägt fehl, wenn sich der Prozess bereits im Hintergrundverarbeitungsmodus befindet. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
PROCESS_MODE_BACKGROUND_END 0x00200000	Beenden des Hintergrundverarbeitungsmodus. Das System stellt die Ressourcenplanungsprioritäten des Prozesses (und seiner Threads) wie vor dem Eintritt in den Hintergrundverarbeitungsmodus wieder her. Dieser Wert kann nur angegeben werden, wenn hProcess ein Handle für den aktuellen Prozess ist. Die Funktion schlägt fehl, wenn sich der Prozess nicht im Hintergrundverarbeitungsmodus befindet. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
REALTIME_PRIORITY_CLASS 0x00000100	Prozess, der die höchstmögliche Priorität hat. Die Threads des Prozesses verdrängen die Threads aller anderen Prozesse, einschließlich Betriebssystemprozessen, die wichtige Aufgaben ausführen. Beispielsweise kann ein Echtzeitprozess, der länger als ein sehr kurzes Intervall ausgeführt wird, dazu führen, dass Datenträgercaches nicht geleert werden oder die Maus nicht mehr reagiert.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Jeder Thread verfügt über eine Basisprioritätsebene, die durch den Prioritätswert des Threads und die Prioritätsklasse des Prozesses bestimmt wird. Das System verwendet die Basisprioritätsebene aller ausführbaren Threads, um zu bestimmen, welcher Thread den nächsten Slice der CPU-Zeit erhält. Die SetThreadPriority-Funktion ermöglicht das Festlegen der Basisprioritätsebene eines Threads relativ zur Prioritätsklasse seines Prozesses. Weitere Informationen finden Sie unter Planungsprioritäten.

Die Werte *_PRIORITY_CLASS wirken sich auf die CPU-Planungspriorität des Prozesses aus. Für Prozesse, die Hintergrundarbeit wie Datei-E/A, Netzwerk-E/A oder Datenverarbeitung ausführen, reicht es nicht aus, die CPU-Planungspriorität anzupassen. selbst ein CPU-Prioritätsprozess im Leerlauf kann die Systemreaktion leicht beeinträchtigen, wenn er den Datenträger und den Arbeitsspeicher verwendet. Prozesse, die Hintergrundarbeit ausführen, sollten die PROCESS_MODE_BACKGROUND_BEGIN - und PROCESS_MODE_BACKGROUND_END-Werte verwenden, um ihre Ressourcenplanungsprioritäten anzupassen. Prozesse, die mit dem Benutzer interagieren, sollten nicht PROCESS_MODE_BACKGROUND_BEGIN verwenden.

Wenn sich ein Prozess im Hintergrundverarbeitungsmodus befindet, befinden sich die neuen Threads, die er erstellt, ebenfalls im Hintergrundverarbeitungsmodus. Wenn sich ein Thread im Hintergrundverarbeitungsmodus befindet, sollte er die Freigabe von Ressourcen wie kritische Abschnitte, Heaps und Handles mit anderen Threads im Prozess minimieren, da andernfalls Prioritätsinversionen auftreten können. Wenn Threads mit hoher Priorität ausgeführt werden, wird ein Thread im Hintergrundverarbeitungsmodus möglicherweise nicht sofort geplant, aber er wird nie ausgehungert.

Jeder Thread kann mit SetThreadPriority unabhängig in den Hintergrundverarbeitungsmodus wechseln. Rufen Sie SetPriorityClass nicht auf, um in den Hintergrundverarbeitungsmodus zu wechseln, nachdem ein Thread im Prozess SetThreadPriority aufgerufen hat, um in den Hintergrundverarbeitungsmodus zu wechseln. Nachdem ein Prozess den Hintergrundverarbeitungsmodus beendet hat, setzt er alle Threads im Prozess zurück. Es ist jedoch nicht möglich, dass der Prozess weiß, welche Threads sich bereits im Hintergrundverarbeitungsmodus befanden.

Beispiele

Im folgenden Beispiel wird die Verwendung des Prozesshintergrundmodus veranschaulicht.

#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;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	processthreadsapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll