Funzione SetThreadInformation (processthreadsapi.h)

Articolo
03/08/2023

Imposta le informazioni per il thread specificato.

Sintassi

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

Parametri

[in] hThread

Handle per il thread. L'handle deve avere THREAD_SET_INFORMATION diritto di accesso. Per altre informazioni, vedere Thread Security and Access Rights.For more information, see Thread Security and Access Rights.

[in] ThreadInformationClass

Classe di informazioni da impostare. Gli unici valori supportati sono ThreadMemoryPriority e ThreadPowerThrottling.

ThreadInformation

Puntatore a una struttura che contiene il tipo di informazioni specificato dal parametro ThreadInformationClass .

Se il parametro ThreadInformationClass è ThreadMemoryPriority, questo parametro deve puntare a una struttura MEMORY_PRIORITY_INFORMATION .

Se il parametro ThreadInformationClass è ThreadPowerThrottling, questo parametro deve puntare a una struttura THREAD_POWER_THROTTLING_STATE .

[in] ThreadInformationSize

Dimensione in byte della struttura specificata dal parametro ThreadInformation .

Se il parametro ThreadInformationClass è ThreadMemoryPriority, questo parametro deve essere sizeof(MEMORY_PRIORITY_INFORMATION).

Se il parametro ThreadInformationClass è ThreadPowerThrottling, questo parametro deve essere sizeof(THREAD_POWER_THROTTLING_STATE).

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Per migliorare le prestazioni del sistema, le applicazioni devono usare la funzione SetThreadInformation con ThreadMemoryPriority per ridurre la priorità di memoria dei thread che eseguono operazioni in background o accedono a file e dati a cui non si prevede di accedere di nuovo presto. Ad esempio, un'applicazione antimalware potrebbe ridurre la priorità dei thread coinvolti nell'analisi dei file.

La priorità di memoria consente di determinare per quanto tempo le pagine rimangono nel working set di un processo prima che vengano tagliate. La priorità di memoria di un thread determina la priorità minima delle pagine fisiche aggiunte al processo impostato da tale thread. Quando gestione memoria taglia il working set, taglia le pagine con priorità inferiore prima delle pagine con priorità più alta. Ciò migliora le prestazioni complessive del sistema perché è meno probabile che le pagine con priorità più alta vengano eliminate dal working set e quindi attivano un errore di pagina quando si accede di nuovo.

ThreadPowerThrottling consente di limitare i criteri in un thread, che può essere usato per bilanciare le prestazioni e l'efficienza energetica nei casi in cui le prestazioni ottimali non sono necessarie. Quando un thread sceglie di abilitare THREAD_POWER_THROTTLING_EXECUTION_SPEED, il thread verrà classificato come EcoQoS. Il sistema tenterà di aumentare l'efficienza energetica tramite strategie come la riduzione della frequenza della CPU o l'uso di core più efficienti in termini di potenza. EcoQoS deve essere usato quando il lavoro non contribuisce all'esperienza utente in primo piano, che garantisce una maggiore durata della batteria e riduzione del calore e rumore della ventola. EcoQoS non deve essere usato per le esperienze utente in primo piano o critiche per le prestazioni. Prima di Windows 11, il livello EcoQoS non esisteva e il processo veniva invece etichettato come LowQoS. Se un'applicazione non abilita THREAD_POWER_THROTTLING_EXECUTION_SPEEDin modo esplicito , il sistema userà le proprie euristiche per dedurre automaticamente un livello qualità di servizio. Per altre informazioni, vedere Qualità del servizio.

Esempio

L'esempio seguente mostra come chiamare SetThreadInformation con ThreadMemoryPriority per impostare la priorità di memoria bassa sul thread corrente.

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'esempio seguente mostra come chiamare SetThreadInformation con ThreadPowerThrottling per controllare la qualità del servizio di 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));

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	processthreadsapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll

Vedere anche

GetThreadInformation

SetProcessInformation

Share via