KeSetSystemGroupAffinityThread 函式 （wdm.h）
KeSetSystemGroupAffinityThread 例程會變更呼叫線程的組號和親和性遮罩。
語法
void KeSetSystemGroupAffinityThread(
[in] PGROUP_AFFINITY Affinity,
[out, optional] PGROUP_AFFINITY PreviousAffinity
);
參數
[in] Affinity
GROUP_AFFINITY 結構的指標，指定呼叫線程的新組號和群組相對親和性遮罩。
[out, optional] PreviousAffinity
呼叫端配置的 GROUP_AFFINITY 結構的指標，例程會將呼叫線程先前群組親和性的相關信息寫入其中。 呼叫端稍後可以使用此指標作為 KeRevertToUserGroupAffinityThread 例程的輸入參數，以還原先前的線程親和性。 通常，KeSetSystemGroupAffinityThread 將值寫入這個結構，這些結構不是有效的群組親和性，但對於 KeRevertToUserGroupAffinityThread具有特殊意義。 請勿將這些特殊值的指標提供為後續 KeSetSystemGroupAffinityThread 呼叫中的 Affinity 參數。
如有必要，呼叫端可以多次呼叫 KeSetSystemGroupAffinityThread 多次來變更線程親和性。 在這些呼叫的第一個期間，呼叫端應該為 PreviousAffinity 指定非NULL 值，以便擷取原始線程親和性，並在稍後還原。 不過，稍後呼叫 KeSetSystemGroupAffinityThread 可以設定 PreviousAffinity = NULL。 如需詳細資訊，請參閱。
傳回值
沒有
言論
此例程會變更呼叫線程的組號和群組相對親和性遮罩。 Affinity 參數指向 GROUP_AFFINITY 結構。 此結構中的組號和親和性遮罩會識別線程可執行的一組處理器。 如果成功，例程會將線程排程在此集合中的處理器上執行。
如果 PreviousAffinity 參數為非NULL，則例程會儲存先前群組親和性的相關信息，而先前群組親和性會在呼叫開始時生效，位於 PreviousAffinity 指向的 GROUP_AFFINITY 結構中。 若要還原先前的線程親和性，呼叫端可以將這個結構的指標作為輸入參數提供給 KeRevertToUserGroupAffinityThread 例程。
在多處理器系統中，在使用者模式線程內容中執行的核心模式驅動程式例程可能需要呼叫 KeSetSystemGroupAffinityThread，以暫時變更線程的群組親和性。 在例程結束之前，它應該呼叫 KeRevertToUserGroupAffinityThread，將線程的親和性遮罩還原為其原始值。
一個進程一次可以有一個以上的群組的親和性。 不過，線程隨時只能指派給一個群組。 該群組一律位於線程進程的親和性中。 線程可以藉由呼叫KeSetSystemGroupAffinityThread ，將它指派的群組變更為 。
KeSetSystemGroupAffinityThread 將組號和親和性遮罩變更為 *Affinity 中指定的值，前提是下列為 true：
- 組號有效。
- 親和性遮罩有效（也就是說，只會設定對應至群組中邏輯處理器的遮罩位）。
- 至少有一個在親和性遮罩中指定的處理器為使用中。
此外，KeSetSystemGroupAffinityThread 會將零寫入 *PreviousAffinity 中的群組編號和親和性遮罩， 如果先前群組親和性是在使用者模式中指派給線程。 為了回應群組編號和親和性遮罩都是零的 GROUP_AFFINITY 結構，KeRevertToUserGroupAffinityThread 還原目前的使用者模式線程親和性。 如果使用者模式線程親和性在 KeSetSystemGroupAffinityThread 和 KeRevertToUserGroupAffinityThread 呼叫之間變更，則會將最新的使用者模式親和性指派給線程。 （應用程式可以呼叫函式，例如 SetThreadGroupAffinity，以變更線程的使用者模式群組親和性。
在 *Affinity 中的新親和性遮罩生效之前，KeSetSystemGroupAffinityThread 會移除任何對應至目前作用中處理器的親和性遮罩位（設定為零）。 在後續 KeSetSystemGroupAffinityThread 呼叫中，例程寫入 *PreviousAffinity 的值可能包含以這種方式修改的親和性遮罩。
KeSetSystemAffinityThreadEx相關的例程會變更呼叫線程的親和性遮罩，但此例程不同於 KeSetSystemGroupAffinityThread，不接受組號做為輸入參數。 從 Windows 7 開始，KeSetSystemAffinityThreadEx 假設同質遮罩是指群組 0 中的處理器，這與舊版 Windows 不支援群組的這個例程行為相容。 此行為可確保呼叫 KeSetSystemAffinityThreadEx 的現有驅動程式，且在具有兩個以上群組的多重處理器系統中，不會正確執行任何群組導向功能。 不過，在 Windows 7 和更新版本中使用任何群組導向功能的驅動程式應該呼叫 KeSetSystemGroupAffinityThread，而不是 KeSetSystemAffinityThreadEx。
KeSetSystemGroupAffinityThread 和 KeRevertToUserGroupAffinityThread 支持各種不同的呼叫模式。 下圖顯示兩個範例。
下圖代表驅動程式線程，會呼叫 KeSetSystemGroupAffinityThread 三次來變更線程親和性，然後呼叫 KeRevertToUserGroupAffinityThread 以還原原始線程親和性。
在上圖中，標示為「設定親和性」的三個方塊會呼叫 KeSetSystemGroupAffinityThread，而標示為 「還原親和性」的方塊則是呼叫 KeRevertToUserGroupAffinityThread。 第一個 KeSetSystemGroupAffinityThread 呼叫會使用 PreviousAffinity 輸出指標來儲存原始線程親和性。 在接下來的兩次呼叫中，KeSetSystemGroupAffinityThread （以星號標示），呼叫者會將 PreviousAffinity 設定為 NULL。 線程結束之前，它會呼叫 KeRevertToUserGroupAffinityThread，以還原第一個 KeSetSystemGroupAffinityThread 呼叫所儲存的線程親和性。
下圖顯示有點不同的呼叫模式，其中一組 KeSetSystemGroupAffinityThread 和 KeRevertToUserGroupAffinityThread 呼叫是巢狀的。 在此圖表中，驅動程式線程中 KeSetSystemGroupAffinityThread 的每個呼叫都會使用 PreviousAffinity 輸出參數來儲存先前的線程親和性，而且每個呼叫都會與呼叫配對，KeRevertToUserGroupAffinityThread 還原已儲存的線程親和性。
在上圖中，驅動程式線程中的函式 A 會呼叫函式 B 兩次。 假設在函式 A 的專案上，線程仍具有使用者模式應用程式指派給它的親和性。 因此，函式 A 中的 KeSetSystemGroupAffinityThread 呼叫會儲存原始的使用者模式線程親和性。 在第一次呼叫函式 B 時，KeSetSystemGroupAffinityThread 會將驅動程式指派的線程親和性儲存在函式 A 中，以及 KeRevertToUserGroupAffinityThread 的對應呼叫， 還原此親和性。 B 傳回之後，A 中的 KeRevertToUserGroupAffinityThread 會還原原始的使用者模式線程親和性。 在第二次呼叫 B 期間，KeSetSystemGroupAffinityThread 呼叫會儲存原始的使用者模式線程親和性，以及對 KeRevertToUserGroupAffinityThread 的對應呼叫， 還原此親和性。 此範例的重點是，函式 B 不需要知道呼叫端 （function A） 是否在呼叫 B 之前，將線程親和性變更為驅動程式定義的值。
如果在 IRQL <= APC_LEVEL 呼叫 KeSetSystemGroupAffinityThread，而且呼叫成功，則新的群組親和性會立即生效。 當呼叫傳回時，呼叫線程已在新群組親和性中指定的處理器上執行。 如果在 IRQL = DISPATCH_LEVEL呼叫 KeSetSystemGroupAffinityThread，而且呼叫成功，則擱置處理器變更會延遲，直到呼叫者降低低於 DISPATCH_LEVEL 的 IRQL 為止。
從 Windows 11 和 Windows Server 2022 開始，在具有 64 個以上的處理器、進程和線程親和性的系統上，預設會跨越所有 處理器群組。 若要在多個處理器群組上設定線程的系統群組親和性，請使用 PsSetSystemMultipleGroupAffinityThread。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | 從 Windows 7 開始提供。 |
| 目標平臺 | 普遍 |
| 標頭 | wdm.h （包括 Wdm.h、Wdm.h、Ntifs.h） |
| 連結庫 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL （請參閱一節）。 |
| DDI 合規性規則 | HwStorPortProhibitedDIs（storport），PowerIrpDDis（wdm） |