Função KeSetSystemGroupAffinityThread (wdm.h)
A rotina KeSetSystemGroupAffinityThread altera o número do grupo e a máscara de afinidade do thread de chamada.
void KeSetSystemGroupAffinityThread(
[in] PGROUP_AFFINITY Affinity,
[out, optional] PGROUP_AFFINITY PreviousAffinity
);
[in] Affinity
Um ponteiro para uma estrutura de GROUP_AFFINITY que especifica o novo número de grupo e a máscara de afinidade relativa ao grupo para o thread de chamada.
[out, optional] PreviousAffinity
Um ponteiro para uma estrutura de GROUP_AFFINITY alocada pelo chamador na qual a rotina grava informações sobre a afinidade de grupo anterior do thread de chamada. Posteriormente, o chamador pode usar esse ponteiro como um parâmetro de entrada para o KeRevertToUserGroupAffinityThread rotina para restaurar a afinidade de thread anterior. Frequentemente, KeSetSystemGroupAffinityThread grava valores nessa estrutura que não são afinidades de grupo válidas, mas que têm um significado especial para KeRevertToUserGroupAffinityThread. Não forneça ponteiros para esses valores especiais como parâmetros affinity em chamadas KeSetSystemGroupAffinityThread subsequentes.
Se necessário, o chamador pode alterar a afinidade de thread mais de uma vez chamando KeSetSystemGroupAffinityThread várias vezes. Durante a primeira dessas chamadas, o chamador deve especificar um valor deNULL não para PreviousAffinity para que a afinidade de thread original possa ser capturada e restaurada posteriormente. No entanto, as chamadas posteriores para KeSetSystemGroupAffinityThread podem, como opção, definir PreviousAffinity = NULL. Para obter mais informações, consulte Comentários.
Nenhum
Essa rotina altera o número do grupo e a máscara de afinidade relativa ao grupo do thread de chamada. O parâmetro Affinity aponta para uma estrutura GROUP_AFFINITY. O número de grupo e a máscara de afinidade nessa estrutura identificam um conjunto de processadores nos quais o thread pode ser executado. Se bem-sucedida, a rotina agenda o thread a ser executado em um processador neste conjunto.
Se o parâmetro PreviousAffinity não forNULL, a rotina salvará informações sobre a afinidade de grupo anterior, que estavam em vigor no início da chamada, na estrutura GROUP_AFFINITY à qual PreviousAffinity aponta. Para restaurar a afinidade de thread anterior, o chamador pode fornecer o ponteiro para essa estrutura como um parâmetro de entrada para a rotina KeRevertToUserGroupAffinityThread.
Em um sistema multiprocessador, uma rotina de driver no modo kernel executada no contexto de um thread de modo de usuário pode precisar chamar KeSetSystemGroupAffinityThread para alterar temporariamente a afinidade de grupo do thread. Antes que a rotina seja encerrada, ela deve chamar KeRevertToUserGroupAffinityThffinityThread para restaurar a máscara de afinidade do thread para seu valor original.
Um processo pode ter afinidade para mais de um grupo por vez. No entanto, um thread pode ser atribuído a apenas um grupo a qualquer momento. Esse grupo está sempre na afinidade do processo do thread. Um thread pode alterar o grupo ao qual ele é atribuído chamando KeSetSystemGroupAffinityThread.
KeSetSystemGroupAffinityThread altera o número do grupo e a máscara de afinidade para os valores especificados em *Affinity somente se o seguinte for verdadeiro:
- O número do grupo é válido.
- A máscara de afinidade é válida (ou seja, somente os bits de máscara que correspondem aos processadores lógicos no grupo são definidos).
- Pelo menos um dos processadores especificados na máscara de afinidade está ativo.
Além disso, KeSetSystemGroupAffinityThread grava zero no número do grupo e na máscara de afinidade em *PreviousAffinity se a afinidade de grupo anterior foi atribuída ao thread no modo de usuário. Em resposta a uma estrutura GROUP_AFFINITY na qual o número de grupo e a máscara de afinidade são zero, KeRevertToUserGroupAffinityThread restaura a afinidade de thread atual do modo de usuário. Se a afinidade de thread do modo de usuário mudar entre as chamadas KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread chamadas, a afinidade mais recente do modo de usuário será atribuída ao thread. (Um aplicativo pode chamar uma função como SetThreadGroupAffinity para alterar a afinidade de grupo de modo de usuário de um thread.)
Antes que a nova máscara de afinidade em *Affinity entre em vigor, KeSetSystemGroupAffinityThread remove (define como zero) quaisquer bits de máscara de afinidade que correspondam a processadores que não estão ativos no momento. Em uma chamada KeSetSystemGroupAffinityThread subsequente, o valor que a rotina grava em * PreviousAffinity pode conter uma máscara de afinidade que foi modificada dessa forma.
Uma rotina relacionada, KeSetSystemAffinityThreadEx, altera a máscara de afinidade do thread de chamada, mas essa rotina, ao contrário de KeSetSystemGroupAffinityThread, não aceita um número de grupo como um parâmetro de entrada. A partir do Windows 7, KeSetSystemAffinityThreadEx pressupõe que a máscara de afinidade se refere a processadores no grupo 0, que é compatível com o comportamento dessa rotina em versões anteriores do Windows que não dão suporte a grupos. Esse comportamento garante que os drivers existentes que chamam KeSetSystemAffinityThreadEx e que não usam recursos orientados a grupos sejam executados corretamente em sistemas multiprocessadores que tenham dois ou mais grupos. No entanto, os drivers que usam recursos orientados a grupos no Windows 7 e versões posteriores do sistema operacional Windows devem chamar KeSetSystemGroupAffinityThread em vez de KeSetSystemAffinityThreadEx.
KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread dão suporte a uma variedade de padrões de chamada. Dois exemplos são mostrados nos diagramas a seguir.
O diagrama a seguir representa um thread de driver que chama KeSetSystemGroupAffinityThread três vezes para alterar a afinidade de thread e chama KeRevertToUserGroupAffinityThread para restaurar a afinidade de thread original.
No diagrama anterior, as três caixas rotuladas como "Afinidade de conjunto" são chamadas para KeSetSystemGroupAffinityThread e a caixa rotulada "Reverter afinidade" é uma chamada para KeRevertToUserGroupAffinityThread. A primeira chamada KeSetSystemGroupAffinityThread usa o ponteiro de saída PreviousAffinity para salvar a afinidade de thread original. Nas duas chamadas seguintes para KeSetSystemGroupAffinityThread (marcado com asteriscos), o chamador define PreviousAffinity como NULL. Antes que o thread seja encerrado, ele chama KeRevertToUserGroupAffinityThread para restaurar a afinidade de thread salva pela primeira chamada KeSetSystemGroupAffinityThread.
O diagrama a seguir mostra um padrão de chamada um pouco diferente no qual pares de KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread chamadas são aninhados. Neste diagrama, cada chamada para KeSetSystemGroupAffinityThread no thread de driver usa o parâmetro de saída PreviousAffinity para salvar a afinidade de thread anterior e cada uma dessas chamadas é emparelhada com uma chamada para keRevertToUserGroupAffinityThread que restaura a afinidade de thread salva.
No diagrama anterior, a função A no thread de driver chama a função B duas vezes. Suponha que, na entrada para a função A, o thread ainda tenha a afinidade atribuída a ele pelo aplicativo de modo de usuário. Assim, o KeSetSystemGroupAffinityThread chamada na função A salva a afinidade de thread original no modo de usuário. Durante a primeira chamada para a função B, o KeSetSystemGroupAffinityThread salva a afinidade de thread atribuída pelo driver na função A e a chamada correspondente para KeRevertToUserGroupAffinityThread restaura essa afinidade. Após o retorno de B, o KeRevertToUserGroupAffinityThread em A restaura a afinidade de thread original no modo de usuário. Durante a segunda chamada para B, a chamada KeSetSystemGroupAffinityThread salva a afinidade de thread original no modo de usuário e a chamada correspondente para KeRevertToUserGroupAffinityThread restaura essa afinidade. O ponto deste exemplo é que a função B não precisa saber se o chamador (função A) alterou a afinidade de thread para um valor definido pelo driver antes de chamar B.
Se KeSetSystemGroupAffinityThread for chamado em IRQL <= APC_LEVEL e a chamada for bem-sucedida, a nova afinidade de grupo entrará em vigor imediatamente. Quando a chamada retorna, o thread de chamada já está em execução em um processador especificado na nova afinidade de grupo. Se KeSetSystemGroupAffinityThread for chamado em IRQL = DISPATCH_LEVEL e a chamada for bem-sucedida, a alteração pendente do processador será adiada até que o chamador reduza o IRQL abaixo DISPATCH_LEVEL.
A partir do Windows 11 e do Windows Server 2022, em um sistema com mais de 64 processadores, afinidades de processo e thread abrangem todos os processadores do sistema, em todos os grupos de processadores , por padrão. Para definir a afinidade de grupo do sistema de um thread em vários grupos de processadores, use PsSetSystemMultipleGroupAffinityThread.
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows 7. |
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Wdm.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL (consulte a seção Comentários). |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |