Share via

Función SetThreadInformation (processthreadsapi.h)

  • Artículo

Establece información para el subproceso especificado.

Sintaxis

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

Parámetros

[in] hThread

Identificador del subproceso. El identificador debe tener THREAD_SET_INFORMATION derecho de acceso. Para obtener más información, consulte Derechos de acceso y seguridad de subprocesos.

[in] ThreadInformationClass

Clase de información que se va a establecer. Los únicos valores admitidos son ThreadMemoryPriority y ThreadPowerThrottling.

ThreadInformation

Puntero a una estructura que contiene el tipo de información especificada por el parámetro ThreadInformationClass .

Si el parámetro ThreadInformationClass es ThreadMemoryPriority, este parámetro debe apuntar a una estructura MEMORY_PRIORITY_INFORMATION .

Si el parámetro ThreadInformationClass es ThreadPowerThrottling, este parámetro debe apuntar a una estructura THREAD_POWER_THROTTLING_STATE .

[in] ThreadInformationSize

Tamaño en bytes de la estructura especificada por el parámetro ThreadInformation .

Si el parámetro ThreadInformationClass es ThreadMemoryPriority, este parámetro debe ser sizeof(MEMORY_PRIORITY_INFORMATION).

Si el parámetro ThreadInformationClass es ThreadPowerThrottling, este parámetro debe ser sizeof(THREAD_POWER_THROTTLING_STATE).

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Para ayudar a mejorar el rendimiento del sistema, las aplicaciones deben usar la función SetThreadInformation con ThreadMemoryPriority para reducir la prioridad de memoria de los subprocesos que realizan operaciones en segundo plano o acceden a archivos y datos a los que no se espera que se vuelva a acceder pronto. Por ejemplo, una aplicación antimalware podría reducir la prioridad de los subprocesos implicados en el examen de archivos.

La prioridad de memoria ayuda a determinar cuánto tiempo permanecen las páginas en el conjunto de trabajo de un proceso antes de que se recorten. La prioridad de memoria de un subproceso determina la prioridad mínima de las páginas físicas que se agregan al conjunto de trabajo del proceso mediante ese subproceso. Cuando el administrador de memoria recorta el espacio de trabajo, recorta las páginas de prioridad inferior antes de las páginas de prioridad más alta. Esto mejora el rendimiento general del sistema porque es menos probable que las páginas de prioridad más alta se recorten del espacio de trabajo y, a continuación, desencadenen un error de página cuando se vuelva a acceder a ellas.

ThreadPowerThrottling permite las directivas de limitación en un subproceso, que se pueden usar para equilibrar el rendimiento y la eficiencia energética en los casos en los que no se requiere un rendimiento óptimo. Cuando un subproceso opta por habilitar THREAD_POWER_THROTTLING_EXECUTION_SPEED, el subproceso se clasificará como EcoQoS. El sistema intentará aumentar la eficiencia energética mediante estrategias como reducir la frecuencia de CPU o usar núcleos más eficientes. EcoQoS debe utilizarse cuando el trabajo no contribuye a la experiencia del usuario en primer plano, lo que proporciona una mayor duración de la batería y reduce el ruido de calor y ventilador. EcoQoS no debe usarse para experiencias de usuario críticas o en primer plano del rendimiento. (Antes de Windows 11, el nivel EcoQoS no existía y el proceso se etiquetaba en su lugar como LowQoS). Si una aplicación no habilita THREAD_POWER_THROTTLING_EXECUTION_SPEEDexplícitamente , el sistema usará su propia heurística para deducir automáticamente un nivel de calidad de servicio. Para obtener más información, consulte Calidad de servicio.

Ejemplos

En el ejemplo siguiente se muestra cómo llamar a SetThreadInformation con ThreadMemoryPriority para establecer una prioridad de memoria baja en el subproceso actual.

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

En el ejemplo siguiente se muestra cómo llamar a SetThreadInformation con ThreadPowerThrottling para controlar la calidad de servicio de un subproceso.

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

Requisitos

Requisito Value
Cliente mínimo compatible Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado processthreadsapi.h (incluya Windows.h)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

GetThreadInformation

SetProcessInformation