Função SetThreadPriority (processthreadsapi.h)

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

Sintaxe

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

Parâmetros

[in] hThread

Um identificador para o thread cujo valor de prioridade deve ser definido.

O identificador deve ter o acesso THREAD_SET_INFORMATION ou THREAD_SET_LIMITED_INFORMATION correto. Para obter mais informações, consulte Segurança de thread e direitos de acesso. Windows Server 2003: O identificador deve ter o acesso de THREAD_SET_INFORMATION correto.

[in] nPriority

O valor de prioridade para o thread. Esse parâmetro pode usar um dos valores a seguir.

Se o thread tiver a classe base REALTIME_PRIORITY_CLASS , esse parâmetro também poderá ser -7, -6, -5, -4, -3, 3, 4, 5 ou 6. Para obter mais informações, consulte Prioridades de agendamento.

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.

Windows Phone 8.1: os aplicativos da Windows Phone Store podem chamar essa função, mas ela não tem efeito. A função retornará um valor diferente de zero indicando êxito.

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. Os threads são agendados de forma round robin em cada nível de prioridade e somente quando não há threads executáveis em um nível mais alto o agendamento de threads em um nível inferior ocorre.

A função SetThreadPriority permite definir o nível de prioridade base de um thread em relação à classe de prioridade de seu processo. Por exemplo, especificar THREAD_PRIORITY_HIGHEST em uma chamada para SetThreadPriority para um thread de um processo de IDLE_PRIORITY_CLASS define o nível de prioridade base do thread como 6. Para obter uma tabela que mostra os níveis de prioridade base para cada combinação de valor de prioridade de classe e prioridade de thread, consulte Prioridades de agendamento.

Para processos IDLE_PRIORITY_CLASS, BELOW_NORMAL_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, ABOVE_NORMAL_PRIORITY_CLASS e HIGH_PRIORITY_CLASS , o sistema aumenta dinamicamente o nível de prioridade base de um thread quando ocorrem eventos que são importantes para o thread. REALTIME_PRIORITY_CLASS processos não recebem impulsos dinâmicos.

Todos os threads inicialmente começam em THREAD_PRIORITY_NORMAL. Use as funções GetPriorityClass e SetPriorityClass para obter e definir a classe de prioridade de um processo. Use a função GetThreadPriority para obter o valor de prioridade de um thread.

Use a classe de prioridade de um processo para diferenciar entre aplicativos que são críticos por tempo e aqueles que têm requisitos de agendamento normais ou abaixo do normal. Use valores de prioridade de thread para diferenciar as prioridades relativas das tarefas de um processo. Por exemplo, um thread que manipula a entrada de uma janela pode ter um nível de prioridade mais alto do que um thread que executa cálculos intensivos para a CPU.

Ao manipular prioridades, tenha muito cuidado para garantir que um thread de alta prioridade não consuma todo o tempo de CPU disponível. Um thread com um nível de prioridade base acima de 11 interfere na operação normal do sistema operacional. Usar REALTIME_PRIORITY_CLASS pode fazer com que os caches de disco não sejam liberados, fazer com que o mouse pare de responder e assim por diante.

Os valores THREAD_PRIORITY_* afetam a prioridade de agendamento da CPU do thread. Para threads 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 thread de prioridade de CPU ocioso pode interferir facilmente na capacidade de resposta do sistema quando usa o disco e a memória. Os threads que executam o trabalho em segundo plano devem usar os valores THREAD_MODE_BACKGROUND_BEGIN e THREAD_MODE_BACKGROUND_END para ajustar suas prioridades de agendamento de recursos; threads que interagem com o usuário não devem usar THREAD_MODE_BACKGROUND_BEGIN.

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.

Windows Server 2008 e Windows Vista: Enquanto o sistema está sendo iniciado, a função SetThreadPriority retorna um valor de retorno de êxito, mas não altera a prioridade do thread para aplicativos iniciados na pasta Inicialização do sistema ou listados na chave do Registro de Execução do SOFTWARE\microsoft\Windows\CurrentVersion\do software do HKEY_LOCAL_MACHINE\. Esses aplicativos são executados com prioridade reduzida por um curto período (aproximadamente 60 segundos) para tornar o sistema mais responsivo às ações do usuário durante a inicialização.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store.

Windows Phone aplicativos da Loja 8.1:Windows Phone podem chamar essa função, mas ela não tem efeito.

Exemplos

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

Requisitos

Confira também

GetPriorityClass

Getthreadpriority

Funções de thread e processo

Prioridades de agendamento

SetPriorityClass

Threads