Função SetPriorityClass (processthreadsapi.h)

Artigo
03/08/2023

Define a classe de prioridade para o processo especificado. Esse valor junto com o valor de prioridade de cada thread do processo determina o nível de prioridade base de cada thread.

Sintaxe

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

Parâmetros

[in] hProcess

Um identificador para o processo.

O identificador deve ter o acesso PROCESS_SET_INFORMATION correto. Para obter mais informações, consulte Direitos de Acesso e Segurança do Processo.

[in] dwPriorityClass

A classe de prioridade para o processo. Esse parâmetro pode usar um dos valores a seguir.

Prioridade	Significado
ABOVE_NORMAL_PRIORITY_CLASS 0x00008000	Processo que tem prioridade acima de NORMAL_PRIORITY_CLASS , mas abaixo HIGH_PRIORITY_CLASS.
BELOW_NORMAL_PRIORITY_CLASS 0x00004000	Processo que tem prioridade acima de IDLE_PRIORITY_CLASS , mas abaixo NORMAL_PRIORITY_CLASS.
HIGH_PRIORITY_CLASS 0x00000080	Processo que executa tarefas críticas de tempo que devem ser executadas imediatamente. Os threads do processo capturam os threads de processos da classe de prioridade normal ou ociosa. Um exemplo é a Lista de Tarefas, que deve responder rapidamente quando chamado pelo usuário, independentemente da carga no sistema operacional. Use cuidados extremos ao usar a classe de alta prioridade, pois um aplicativo de classe de alta prioridade pode usar quase todo o tempo de CPU disponível.
IDLE_PRIORITY_CLASS 0x00000040	Processo cujos threads são executados somente quando o sistema está ocioso. Os threads do processo são capturados pelos threads de qualquer processo em execução em uma classe de prioridade mais alta. Um exemplo é uma proteção de tela. A classe de prioridade ociosa é herdada por processos filho.
NORMAL_PRIORITY_CLASS 0x00000020	Processo sem nenhuma necessidade de agendamento especial.
PROCESS_MODE_BACKGROUND_BEGIN 0x00100000	Iniciar o modo de processamento em segundo plano. O sistema reduz as prioridades de agendamento de recursos do processo (e seus threads) para que ele possa executar trabalhos em segundo plano sem afetar significativamente a atividade em primeiro plano. Esse valor só poderá ser especificado se hProcess for um identificador para o processo atual. A função falhará se o processo já estiver no modo de processamento em segundo plano. Windows Server 2003 e Windows XP: Não há suporte para esse valor.
PROCESS_MODE_BACKGROUND_END 0x00200000	Modo de processamento em segundo plano final. O sistema restaura as prioridades de agendamento de recursos do processo (e seus threads) como eram antes do processo entrar no modo de processamento em segundo plano. Esse valor só poderá ser especificado se hProcess for um identificador para o processo atual. A função falhará se o processo não estiver no modo de processamento em segundo plano. Windows Server 2003 e Windows XP: Não há suporte para esse valor.
REALTIME_PRIORITY_CLASS 0x00000100	Processo que tem a prioridade mais alta possível. Os threads do processo preempõem os threads de todos os outros processos, incluindo processos do sistema operacional que executam tarefas importantes. Por exemplo, um processo em tempo real que é executado por mais de um intervalo muito breve pode fazer com que os caches de disco não liberem ou fazem com que o mouse não responda.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Cada thread tem um nível de prioridade base determinado pelo valor de prioridade do thread e pela classe de prioridade de seu processo. O sistema usa o nível de prioridade base de todos os threads executáveis para determinar qual thread obtém a próxima fatia de tempo de CPU. A função SetThreadPriority permite definir o nível de prioridade base de um thread em relação à classe de prioridade de seu processo. Para obter mais informações, consulte Prioridades de agendamento.

Os *_PRIORITY_CLASS valores afetam a prioridade de agendamento da CPU do processo. Para processos que executam trabalhos em segundo plano, como E/S de arquivo, E/S de rede ou processamento de dados, não é suficiente ajustar a prioridade de agendamento da CPU; até mesmo um processo de prioridade de CPU ocioso pode interferir facilmente na capacidade de resposta do sistema quando usa o disco e a memória. Os processos que executam o trabalho em segundo plano devem usar os valores PROCESS_MODE_BACKGROUND_BEGIN e PROCESS_MODE_BACKGROUND_END para ajustar suas prioridades de agendamento de recursos; processos que interagem com o usuário não devem usar PROCESS_MODE_BACKGROUND_BEGIN.

Se um processo estiver no modo de processamento em segundo plano, os novos threads que ele cria também estarão no modo de processamento em segundo plano. Quando um thread está no modo de processamento em segundo plano, ele deve minimizar o compartilhamento de recursos, como seções críticas, heaps e identificadores com outros threads no processo, caso contrário, podem ocorrer inversões prioritárias. Se houver threads em execução em alta prioridade, um thread no modo de processamento em segundo plano poderá não ser agendado imediatamente, mas nunca será ignorado.

Cada thread pode entrar no modo de processamento em segundo plano independentemente usando SetThreadPriority. Não chame SetPriorityClass para entrar no modo de processamento em segundo plano depois que um thread no processo tiver chamado SetThreadPriority para entrar no modo de processamento em segundo plano. Depois que um processo termina o modo de processamento em segundo plano, ele redefine todos os threads no processo; no entanto, não é possível que o processo saiba quais threads já estavam no modo de processamento em segundo plano.

Exemplos

O exemplo a seguir demonstra o uso do modo em segundo plano do 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;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	processthreadsapi.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll