StorPortSetSystemGroupAffinityThread 函式（storport.h）

發行項
02/07/2025

StorPortSetSystemGroupAffinityThread 變更呼叫線程的組號和親和性遮罩。

語法

ULONG StorPortSetSystemGroupAffinityThread(
  [in]           PVOID                HwDeviceExtension,
  [in/optional]  PVOID                ThreadContext,
  [in]           PSTOR_GROUP_AFFINITY Affinity,
  [out/optional] PSTOR_GROUP_AFFINITY PreviousAffinity
);

參數

[in] HwDeviceExtension

迷你埠硬體裝置延伸模組的指標。

[in/optional] ThreadContext

在呼叫 StorPortCreateSystemThread 之前呼叫中收到的線程內容指標，。

[in] Affinity

呼叫端配置的 STOR_GROUP_AFFINITY 結構的指標，這個結構會指定呼叫線程的新組號和群組相對親和性遮罩。

[out/optional] PreviousAffinity

STOR_GROUP_AFFINITY 結構的指標，這個例程會在呼叫之前，為呼叫線程寫入組號和親和性遮罩。這個參數是選擇性的，而且可以是 NULL。

傳回值

StorPortSetSystemGroupAffinityThread 會傳回下列其中一個值：

傳回碼	描述
STOR_STATUS_SUCCESS	已成功設定指定的群組親和性。
STOR_STATUS_INVALID_PARAMETER	提供的一或多個參數無效。
STOR_STATUS_UNSUCCESSFUL	基於其他內部系統原因傳回。

言論

迷你埠可以呼叫 StorPortSetSystemGroupAffinityThread，以變更呼叫線程的組號和群組層級親和性遮罩。

Affinity 所指向之 STOR_GROUP_AFFINITY 結構的組號和親和性遮罩 識別線程可執行的一組處理器。如果成功，StorPortSetSystemGroupAffinityThread 排程線程，以在此集合中的處理器上執行。

如果 PreviousAffinity 參數為非 NULL，StorPortSetSystemGroupAffinityThread 會儲存先前群組親和性的相關信息，而前一個群組親和性會在呼叫開始時生效，PreviousAffinity 指向的 STOR_GROUP_AFFINITY 結構中。若要還原先前的線程親和性，呼叫端可以將這個結構的指標當作輸入參數提供給 StorPortRevertToUserGroupAffinityThread 例程。

如果迷你埠呼叫此函式以暫時變更線程的群組親和性，則它應該呼叫 StorPortRevertToUserGroupAffinityThread，以在線程結束之前將線程親和性還原為其原始值。

線程隨時只能指派給一個群組親和性。該群組一律位於線程進程的親和性中。線程可以藉由呼叫這個例程來變更其指派的群組。

StorPortSetSystemGroupAffinityThread 將組號和親和性遮罩變更為 Affinity 中指定的值，只有在下列為 true 時，才會：

組號有效。
親和性遮罩有效（也就是說，只會設定對應至群組中邏輯處理器的遮罩位）。
至少有一個在親和性遮罩中指定的處理器為使用中。

如果不符合上述任一條件，線程的群組編號和親和性遮罩會保持不變。如果 PreviousAffinity 為非 NULL，則例程會將零寫入 PreviousAffinity中的群組編號和親和性遮罩。

在 Affinity 中的新親和性遮罩生效之前，StorPortSetSystemGroupAffinityThread 會移除任何對應至目前作用中處理器的親和性遮罩位（設定為零）。在後續 StorPortSetSystemGroupAffinityThread 呼叫中，例程寫入 PreviousAffinity 的值可能包含以這種方式修改的親和性遮罩。

如果在 IRQL <= APC_LEVEL 呼叫 storPortSetSystemGroupAffinityThread，而且呼叫成功，新的群組親和性就會立即生效。當呼叫傳回時，呼叫線程已在新群組親和性中指定的處理器上執行。如果 StorPortSetSystemGroupAffinityThread 在 IRQL = DISPATCH_LEVEL且呼叫成功，則擱置處理器變更會延後，直到呼叫者降低低於DISPATCH_LEVEL的 IRQL 為止。