Fungsi SetThreadInformation (processthreadsapi.h)
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 |