SetThreadInformation-Funktion (processthreadsapi.h)

Legt Informationen für den angegebenen Thread fest.

Syntax

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

Parameter

[in] hThread

Ein Handle auf den Thread. Das Handle muss über THREAD_SET_INFORMATION Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Threadsicherheit und Zugriffsrechte.

[in] ThreadInformationClass

Die Klasse der festzulegenden Informationen. Die einzigen unterstützten Werte sind ThreadMemoryPriority und ThreadPowerThrottling.

ThreadInformation

Zeiger auf eine Struktur, die den Vom ThreadInformationClass-Parameter angegebenen Informationstyp enthält.

Wenn der ThreadInformationClass-ParameterThreadMemoryPriority ist, muss dieser Parameter auf eine MEMORY_PRIORITY_INFORMATION-Struktur verweisen.

Wenn der ThreadInformationClass-ParameterThreadPowerThrottling ist, muss dieser Parameter auf eine THREAD_POWER_THROTTLING_STATE-Struktur verweisen.

[in] ThreadInformationSize

Die Größe der vom ThreadInformation-Parameter angegebenen Struktur in Byte.

Wenn der ThreadInformationClass-ParameterThreadMemoryPriority ist, muss dieser Parameter sein sizeof(MEMORY_PRIORITY_INFORMATION).

Wenn der ThreadInformationClass-ParameterThreadPowerThrottling ist, muss dieser Parameter sein sizeof(THREAD_POWER_THROTTLING_STATE).

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Um die Systemleistung zu verbessern, sollten Anwendungen die SetThreadInformation-Funktion mit ThreadMemoryPriority verwenden, um die Arbeitsspeicherpriorität von Threads zu senken, die Hintergrundvorgänge ausführen oder auf Dateien und Daten zugreifen, auf die nicht bald wieder zugegriffen werden soll. Beispielsweise kann eine Antischadsoftwareanwendung die Priorität von Threads verringern, die an der Überprüfung von Dateien beteiligt sind.

Mit der Speicherpriorität kann ermittelt werden, wie lange Seiten im Arbeitssatz eines Prozesses verbleiben, bevor sie gekürzt werden. Die Arbeitsspeicherpriorität eines Threads bestimmt die Mindestpriorität der physischen Seiten, die dem von diesem Thread festgelegten Prozessarbeitsvorgang hinzugefügt werden. Wenn der Arbeitsspeicher-Manager den Arbeitssatz schneidet, schneidet er Seiten mit niedrigerer Priorität vor Seiten mit höherer Priorität ab. Dies verbessert die Gesamtsystemleistung, da Seiten mit höherer Priorität weniger wahrscheinlich aus dem Arbeitssatz entfernt werden und dann einen Seitenfehler auslösen, wenn erneut darauf zugegriffen wird.

ThreadPowerThrottling ermöglicht Drosselungsrichtlinien für einen Thread, die verwendet werden können, um Leistung und Energieeffizienz in Fällen auszugleichen, in denen keine optimale Leistung erforderlich ist. Wenn ein Thread die Aktivierung aktiviert THREAD_POWER_THROTTLING_EXECUTION_SPEED, wird der Thread als EcoQoS klassifiziert. Das System versucht, die Energieeffizienz durch Strategien wie die Verringerung der CPU-Frequenz oder die Verwendung von energieeffizienteren Kernen zu erhöhen. EcoQoS sollte verwendet werden, wenn die Arbeit nicht zur Benutzerfreundlichkeit im Vordergrund beiträgt, was eine längere Akkulaufzeit und geringere Wärme- und Lüftergeräusche bietet. EcoQoS sollte nicht für leistungskritische Benutzeroberflächen oder Benutzeroberflächen im Vordergrund verwendet werden. (Vor Windows 11 war die EcoQoS-Ebene nicht vorhanden, und der Prozess wurde stattdessen als LowQoS bezeichnet. Wenn eine Anwendung nicht explizit aktiviert THREAD_POWER_THROTTLING_EXECUTION_SPEED, verwendet das System eine eigene Heuristik, um automatisch eine Quality of Service-Ebene abzuleiten. Weitere Informationen finden Sie unter Servicequalität.

Beispiele

Das folgende Beispiel zeigt, wie SetThreadInformation mit ThreadMemoryPriority aufgerufen wird, um eine niedrige Arbeitsspeicherpriorität für den aktuellen Thread festzulegen.

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);
}

Das folgende Beispiel zeigt, wie SetThreadInformation mit ThreadPowerThrottling aufgerufen wird, um die Dienstqualität eines Threads zu steuern.

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));

Anforderungen

Siehe auch

GetThreadInformation

SetProcessInformation