Funzione SetPriorityClass (processthreadsapi.h)

Articolo
03/05/2024

Imposta la classe di priorità per il processo specificato. Questo valore insieme al valore di priorità di ogni thread del processo determina il livello di priorità di base di ogni thread.

Sintassi

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

Parametri

[in] hProcess

Handle per il processo.

L'handle deve avere il diritto di accesso PROCESS_SET_INFORMATION . Per altre informazioni, vedere Elaborare diritti di sicurezza e accesso.

[in] dwPriorityClass

Classe di priorità per il processo. Questo parametro può avere uno dei valori seguenti.

Priorità	Significato
ABOVE_NORMAL_PRIORITY_CLASS 0x00008000	Processo con priorità superiore a NORMAL_PRIORITY_CLASS , ma sotto HIGH_PRIORITY_CLASS.
BELOW_NORMAL_PRIORITY_CLASS 0x00004000	Processo con priorità superiore a IDLE_PRIORITY_CLASS , ma sotto NORMAL_PRIORITY_CLASS.
HIGH_PRIORITY_CLASS 0x00000080	Processo che esegue attività time-critical che devono essere eseguite immediatamente. I thread del processo hanno la precedenza sui thread dei processi con classe di priorità normal o idle. Un esempio è l'elenco attività, che deve rispondere rapidamente quando viene chiamato dall'utente, indipendentemente dal carico nel sistema operativo. Usare attenzione estrema quando si usa la classe con priorità elevata, perché un'applicazione di classe con priorità elevata può usare quasi tutto il tempo di CPU disponibile.
IDLE_PRIORITY_CLASS 0x00000040	Elaborare i cui thread vengono eseguiti solo quando il sistema è inattiva. I thread del processo hanno la precedenza sui thread di qualsiasi processo con una classe di priorità superiore. Un esempio è uno screen saver. La classe con priorità inattiva viene ereditata dai processi figlio.
NORMAL_PRIORITY_CLASS 0x00000020	Processo senza esigenze di pianificazione speciali.
PROCESS_MODE_BACKGROUND_BEGIN 0x00100000	Avviare la modalità di elaborazione in background. Il sistema riduce le priorità di pianificazione delle risorse del processo (e dei relativi thread) in modo che possa eseguire operazioni in background senza influire in modo significativo sull'attività in primo piano. Questo valore può essere specificato solo se hProcess è un handle per il processo corrente. La funzione ha esito negativo se il processo è già in modalità di elaborazione in background. Windows Server 2003 e Windows XP: Questo valore non è supportato.
PROCESS_MODE_BACKGROUND_END 0x00200000	Modalità di elaborazione in background finale. Il sistema ripristina le priorità di pianificazione delle risorse del processo (e dei relativi thread) così come erano prima del processo immesso in modalità di elaborazione in background. Questo valore può essere specificato solo se hProcess è un handle per il processo corrente. La funzione ha esito negativo se il processo non è in modalità di elaborazione in background. Windows Server 2003 e Windows XP: Questo valore non è supportato.
REALTIME_PRIORITY_CLASS 0x00000100	Processo con priorità massima possibile. I thread del processo precludono i thread di tutti gli altri processi, inclusi i processi del sistema operativo che eseguono attività importanti. Ad esempio, un processo in tempo reale che viene eseguito per più di un intervallo molto breve può causare la scaricamento della cache dei dischi o la mancata risposta del mouse.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Ogni thread ha un livello di priorità di base determinato dal valore di priorità del thread e dalla classe di priorità del processo. Il sistema usa il livello di priorità di base di tutti i thread eseguibili per determinare quale thread ottiene la sezione successiva del tempo di CPU. La funzione SetThreadPriority consente di impostare il livello di priorità di base di un thread rispetto alla classe di priorità del processo. Per altre informazioni, vedere Pianificazione delle priorità.

I valori *_PRIORITY_CLASS influiscono sulla priorità di pianificazione della CPU del processo. Per i processi che eseguono operazioni in background, ad esempio I/O file, I/O di rete o elaborazione dei dati, non è sufficiente modificare la priorità di pianificazione della CPU; anche un processo di priorità CPU inattiva può interferire facilmente con la velocità di risposta del sistema quando usa il disco e la memoria. I processi che eseguono operazioni in background devono usare i valori PROCESS_MODE_BACKGROUND_BEGIN e PROCESS_MODE_BACKGROUND_END per modificare le priorità di pianificazione delle risorse; i processi che interagiscono con l'utente non devono usare PROCESS_MODE_BACKGROUND_BEGIN.

Se un processo è in modalità di elaborazione in background, i nuovi thread creati saranno anche in modalità di elaborazione in background. Quando un thread è in modalità di elaborazione in background, deve ridurre al minimo le risorse di condivisione, ad esempio sezioni critiche, heaps e handle con altri thread nel processo, altrimenti possono verificarsi inversioni di priorità. Se sono presenti thread in esecuzione con priorità elevata, un thread in modalità di elaborazione in background potrebbe non essere pianificato tempestivamente, ma non verrà mai bloccato.

Ogni thread può immettere la modalità di elaborazione in background in modo indipendente usando SetThreadPriority. Non chiamare SetPriorityClass per immettere la modalità di elaborazione in background dopo che un thread nel processo ha chiamato SetThreadPriority per immettere la modalità di elaborazione in background. Dopo che un processo termina la modalità di elaborazione in background, reimposta tutti i thread nel processo; tuttavia, non è possibile che il processo sappia quali thread erano già in modalità di elaborazione in background.

Esempio

Nell'esempio seguente viene illustrato l'uso della modalità in background del processo.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	processthreadsapi.h (includere Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Libreria	Kernel32.lib
DLL	Kernel32.dll