Fungsi SetThreadInformation (processthreadsapi.h)

Artikel
03/08/2023

Mengatur informasi untuk utas yang ditentukan.

Sintaks

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

Parameter

[in] hThread

Handel ke utas. Handel harus memiliki hak akses THREAD_SET_INFORMATION. Untuk informasi selengkapnya, lihat Keamanan Utas dan Hak Akses.

[in] ThreadInformationClass

Kelas informasi yang akan diatur. Satu-satunya nilai yang didukung adalah ThreadMemoryPriority dan ThreadPowerThrottling.

ThreadInformation

Penunjuk ke struktur yang berisi jenis informasi yang ditentukan oleh parameter ThreadInformationClass .

Jika parameter ThreadInformationClass adalah ThreadMemoryPriority, parameter ini harus menunjuk ke struktur MEMORY_PRIORITY_INFORMATION .

Jika parameter ThreadInformationClass adalah ThreadPowerThrottling, parameter ini harus menunjuk ke struktur THREAD_POWER_THROTTLING_STATE .

[in] ThreadInformationSize

Ukuran dalam byte struktur yang ditentukan oleh parameter ThreadInformation .

Jika parameter ThreadInformationClass adalah ThreadMemoryPriority, parameter ini harus sizeof(MEMORY_PRIORITY_INFORMATION).

Jika parameter ThreadInformationClass adalah ThreadPowerThrottling, parameter ini harus sizeof(THREAD_POWER_THROTTLING_STATE).

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Untuk membantu meningkatkan performa sistem, aplikasi harus menggunakan fungsi SetThreadInformation dengan ThreadMemoryPriority untuk menurunkan prioritas memori utas yang melakukan operasi latar belakang atau mengakses file dan data yang tidak diharapkan akan segera diakses lagi. Misalnya, aplikasi anti-malware mungkin menurunkan prioritas utas yang terlibat dalam file pemindaian.

Prioritas memori membantu menentukan berapa lama halaman tetap berada dalam rangkaian proses yang berfungsi sebelum dipangkas. Prioritas memori utas menentukan prioritas minimum halaman fisik yang ditambahkan ke proses yang berfungsi yang ditetapkan oleh utas tersebut. Saat manajer memori memangkas set kerja, manajer memori memangkas halaman prioritas yang lebih rendah sebelum halaman prioritas yang lebih tinggi. Ini meningkatkan performa sistem secara keseluruhan karena halaman prioritas yang lebih tinggi cenderung tidak dipangkas dari set kerja dan kemudian memicu kesalahan halaman ketika diakses lagi.

ThreadPowerThrottling memungkinkan kebijakan pembatasan pada utas, yang dapat digunakan untuk menyeimbangkan performa dan efisiensi daya jika performa optimal tidak diperlukan. Ketika utas memilih untuk mengaktifkan THREAD_POWER_THROTTLING_EXECUTION_SPEED, utas akan diklasifikasikan sebagai EcoQoS. Sistem akan mencoba meningkatkan efisiensi daya melalui strategi seperti mengurangi frekuensi CPU atau menggunakan inti yang lebih hemat daya. EcoQoS harus digunakan ketika pekerjaan tidak berkontribusi pada pengalaman pengguna latar depan, yang memberikan masa pakai baterai yang lebih lama, dan mengurangi kebisingan panas dan kipas. EcoQoS tidak boleh digunakan untuk pengalaman pengguna kritis performa atau latar depan. (Sebelum Windows 11, tingkat EcoQoS tidak ada dan prosesnya malah diberi label sebagai LowQoS). Jika aplikasi tidak secara eksplisit mengaktifkan THREAD_POWER_THROTTLING_EXECUTION_SPEED, sistem akan menggunakan heuristiknya sendiri untuk secara otomatis menyimpulkan tingkat Kualitas Layanan. Untuk informasi selengkapnya, lihat Kualitas Layanan.

Contoh

Contoh berikut menunjukkan cara memanggil SetThreadInformation dengan ThreadMemoryPriority untuk mengatur prioritas memori rendah pada utas saat ini.

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

Contoh berikut menunjukkan cara memanggil SetThreadInformation dengan ThreadPowerThrottling untuk mengontrol Kualitas Layanan utas.

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [khusus aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 [hanya aplikasi desktop]
Target Platform	Windows
Header	processthreadsapi.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

GetThreadInformation

SetProcessInformation

Bagikan melalui