StorPortSetSystemGroupAffinityThread, fonction (storport.h)

Article
02/07/2025

StorPortSetSystemGroupAffinityThread modifie le numéro de groupe et le masque d’affinité du thread appelant.

Syntaxe

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

Paramètres

[in] HwDeviceExtension

Pointeur vers l’extension d’appareil matériel du miniport.

[in/optional] ThreadContext

Pointeur vers le contexte de thread reçu dans un appel antérieur à StorPortCreateSystemThread.

[in] Affinity

Pointeur vers une structure STOR_GROUP_AFFINITY allouée par l’appelant qui spécifie le nouveau numéro de groupe et le masque d’affinité relative au groupe pour le thread appelant.

[out/optional] PreviousAffinity

Pointeur vers une structure STOR_GROUP_AFFINITY dans laquelle cette routine écrit le numéro de groupe et le masque d’affinité pour le thread appelant avant l’appel. Ce paramètre est facultatif et peut être NULL.

Valeur de retour

StorPortSetSystemGroupAffinityThread retourne l’une des valeurs suivantes :

Retourner le code	Description
STOR_STATUS_SUCCESS	L’affinité de groupe spécifiée a été définie avec succès.
STOR_STATUS_INVALID_PARAMETER	Un ou plusieurs des paramètres fournis ne sont pas valides.
STOR_STATUS_UNSUCCESSFUL	Retourné pour d’autres raisons système internes.

Remarques

Un miniport peut appeler StorPortSetSystemGroupAffinityThread pour modifier le numéro de groupe et le masque d’affinité au niveau du groupe du thread appelant.

Le masque de groupe et d’affinité dans la structure STOR_GROUP_AFFINITY pointée par affinité identifier un ensemble de processeurs sur lesquels le thread peut s’exécuter. Si elle réussit, StorPortSetSystemGroupAffinityThread planifie l’exécution du thread sur un processeur dans cet ensemble.

Si le paramètre PreviousAffinity n’est pas NULL, StorPortSetSystemGroupAffinityThread enregistre des informations sur l’affinité de groupe précédente, qui étaient en vigueur au début de l’appel, dans la structure STOR_GROUP_AFFINITY qui PreviousAffinity pointe vers. Pour restaurer l’affinité de thread précédente, l’appelant peut fournir le pointeur à cette structure en tant que paramètre d’entrée à la routine StorPortRevertToUserGroupAffinityThread.

Si une miniport appelle cette fonction pour modifier temporairement l’affinité de groupe du thread, elle doit appeler StorPortRevertToUserGroupAffinityThread pour rétablir l’affinité de thread à sa valeur d’origine avant la sortie du thread.

Un thread ne peut être affecté qu’à une seule affinité de groupe à tout moment. Ce groupe est toujours dans l’affinité du processus du thread. Un thread peut modifier le groupe auquel il est affecté en appelant cette routine.

StorPortSetSystemGroupAffinityThread remplace le numéro de groupe et le masque d’affinité par les valeurs spécifiées dans Affinity uniquement si les valeurs suivantes sont vraies :

Le numéro de groupe est valide.
Le masque d’affinité est valide (autrement dit, seuls les bits de masque qui correspondent aux processeurs logiques dans le groupe sont définis).
Au moins un des processeurs spécifiés dans le masque d’affinité est actif.

Si l’une de ces conditions n’est pas remplie, le numéro de groupe et le masque d’affinité du thread restent inchangés. Si PreviousAffinity n’est pas NULL, la routine écrit zéro dans le numéro de groupe et le masque d’affinité dans PreviousAffinity.

Avant que le nouveau masque d’affinité dans d’affinité prenne effet, StorPortSetSystemGroupAffinityThread supprime (définit sur zéro) tous les bits de masque d’affinité qui correspondent aux processeurs qui ne sont actuellement pas actifs. Dans un appel de StorPortSetSystemGroupAffinityThread, la valeur que la routine écrit dans PreviousAffinity peut contenir un masque d’affinité qui a été modifié de cette façon.

Si StorPortSetSystemGroupAffinityThread est appelé au <IRQL = APC_LEVEL et que l’appel réussit, la nouvelle affinité de groupe prend effet immédiatement. Lorsque l’appel est retourné, le thread appelant est déjà en cours d’exécution sur un processeur spécifié dans la nouvelle affinité de groupe. Si StorPortSetSystemGroupAffinityThread est appelé à IRQL = DISPATCH_LEVEL et que l’appel réussit, la modification du processeur en attente est différée jusqu’à ce que l’appelant diminue l’IRQL inférieur à DISPATCH_LEVEL.