SetThreadInformation, fonction (processthreadsapi.h)

Article
08/25/2023

Définit les informations du thread spécifié.

Syntaxe

BOOL SetThreadInformation(
  [in] HANDLE                   hThread,
  [in] THREAD_INFORMATION_CLASS ThreadInformationClass,
       LPVOID                   ThreadInformation,
  [in] DWORD                    ThreadInformationSize
);

Paramètres

[in] hThread

Handle pour le thread. Le handle doit avoir THREAD_SET_INFORMATION droit d’accès. Pour plus d’informations, consultez Sécurité des threads et droits d’accès.

[in] ThreadInformationClass

Classe d’informations à définir. Les seules valeurs prises en charge sont ThreadMemoryPriority et ThreadPowerThrottling.

ThreadInformation

Pointeur vers une structure qui contient le type d’informations spécifié par le paramètre ThreadInformationClass .

Si le paramètre ThreadInformationClass est ThreadMemoryPriority, ce paramètre doit pointer vers une structure MEMORY_PRIORITY_INFORMATION .

Si le paramètre ThreadInformationClass est ThreadPowerThrottling, ce paramètre doit pointer vers une structure THREAD_POWER_THROTTLING_STATE .

[in] ThreadInformationSize

Taille en octets de la structure spécifiée par le paramètre ThreadInformation .

Si le paramètre ThreadInformationClass est ThreadMemoryPriority, ce paramètre doit être sizeof(MEMORY_PRIORITY_INFORMATION).

Si le paramètre ThreadInformationClass est ThreadPowerThrottling, ce paramètre doit être sizeof(THREAD_POWER_THROTTLING_STATE).

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour améliorer les performances du système, les applications doivent utiliser la fonction SetThreadInformation avec ThreadMemoryPriority pour réduire la priorité mémoire des threads qui effectuent des opérations en arrière-plan ou accèdent à des fichiers et des données qui ne devraient pas être consultés prochainement. Par exemple, une application anti-programme malveillant peut réduire la priorité des threads impliqués dans l’analyse des fichiers.

La priorité mémoire permet de déterminer la durée pendant laquelle les pages restent dans le jeu de travail d’un processus avant leur suppression. La priorité de mémoire d’un thread détermine la priorité minimale des pages physiques ajoutées au processus défini par ce thread. Lorsque le gestionnaire de mémoire supprime le jeu de travail, il supprime les pages de priorité inférieure avant les pages de priorité plus élevée. Cela améliore les performances globales du système, car les pages de priorité plus élevée sont moins susceptibles d’être supprimées du jeu de travail, puis de déclencher une erreur de page lorsqu’elles sont à nouveau consultées.

ThreadPowerThrottling active des stratégies de limitation sur un thread, qui peuvent être utilisées pour équilibrer les performances et l’efficacité énergétique dans les cas où des performances optimales ne sont pas requises. Lorsqu’un thread choisit d’activer THREAD_POWER_THROTTLING_EXECUTION_SPEED, le thread est classé comme EcoQoS. Le système essaiera d’augmenter l’efficacité énergétique par le biais de stratégies telles que la réduction de la fréquence du processeur ou l’utilisation de cœurs plus économes en énergie. EcoQoS doit être utilisé lorsque le travail ne contribue pas à l’expérience utilisateur de premier plan, ce qui offre une autonomie de la batterie plus longue, et réduit la chaleur et le bruit du ventilateur. EcoQoS ne doit pas être utilisé pour les expériences utilisateur critiques ou au premier plan. (Avant Windows 11, le niveau EcoQoS n’existait pas et le processus était plutôt étiqueté lowQoS). Si une application n’active THREAD_POWER_THROTTLING_EXECUTION_SPEEDpas explicitement , le système utilise ses propres heuristiques pour déduire automatiquement un niveau de qualité de service. Pour plus d’informations, consultez Qualité de service.

Exemples

L’exemple suivant montre comment appeler SetThreadInformation avec ThreadMemoryPriority pour définir une priorité de mémoire faible sur le thread actuel.

DWORD ErrorCode;
BOOL Success;
MEMORY_PRIORITY_INFORMATION MemPrio;

//
// Set low memory priority on the current thread.
//

ZeroMemory(&MemPrio, sizeof(MemPrio));
MemPrio.MemoryPriority = MEMORY_PRIORITY_LOW;

Success = SetThreadInformation(GetCurrentThread(),
                               ThreadMemoryPriority,
                               &MemPrio,
                               sizeof(MemPrio));

if (!Success) {
    ErrorCode = GetLastError();
    fprintf(stderr, "Set thread memory priority failed: %d\n", ErrorCode);
}

L’exemple suivant montre comment appeler SetThreadInformation avec ThreadPowerThrottling pour contrôler la qualité de service d’un thread.

THREAD_POWER_THROTTLING_STATE PowerThrottling;
ZeroMemory(&PowerThrottling, sizeof(PowerThrottling));
PowerThrottling.Version = THREAD_POWER_THROTTLING_CURRENT_VERSION;

//
// EcoQoS
// Turn EXECUTION_SPEED throttling on. 
// ControlMask selects the mechanism and StateMask declares which mechanism should be on or off.
//

PowerThrottling.ControlMask = THREAD_POWER_THROTTLING_EXECUTION_SPEED;
PowerThrottling.StateMask = THREAD_POWER_THROTTLING_EXECUTION_SPEED;

SetThreadInformation(GetCurrentThread(), 
                     ThreadPowerThrottling, 
                     &PowerThrottling, 
                     sizeof(PowerThrottling));

//
// HighQoS
// Turn EXECUTION_SPEED throttling off.
// ControlMask selects the mechanism and StateMask is set to zero as mechanisms should be turned off.
//

PowerThrottling.ControlMask = THREAD_POWER_THROTTLING_EXECUTION_SPEED;
PowerThrottling.StateMask = 0;

SetThreadInformation(GetCurrentThread(), 
                     ThreadPowerThrottling, 
                     &PowerThrottling, 
                     sizeof(PowerThrottling));

//
// Let system manage all power throttling. ControlMask is set to 0 as we don’t want 
// to control any mechanisms.
//

PowerThrottling.ControlMask = 0;
PowerThrottling.StateMask = 0;

SetThreadInformation(GetCurrentThread(), 
                     ThreadPowerThrottling, 
                     &PowerThrottling, 
                     sizeof(PowerThrottling));

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2012 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	processthreadsapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

GetThreadInformation

SetProcessInformation

Partager via