Fungsi KeSetSystemGroupAffinityThread (wdm.h)

Rutinitas KeSetSystemGroupAffinityThread mengubah nomor grup dan masker afinitas utas panggilan.

Sintaks

void KeSetSystemGroupAffinityThread(
  [in]            PGROUP_AFFINITY Affinity,
  [out, optional] PGROUP_AFFINITY PreviousAffinity
);

Parameter

[in] Affinity

Penunjuk ke struktur GROUP_AFFINITY yang menentukan nomor grup baru dan masker afinitas relatif grup untuk utas panggilan.

[out, optional] PreviousAffinity

Penunjuk ke struktur GROUP_AFFINITY yang dialokasikan penelepon tempat rutin menulis informasi tentang afinitas grup sebelumnya dari utas panggilan. Penelepon nantinya dapat menggunakan pointer ini sebagai parameter input ke rutinitas KeRevertToUserGroupAffinityThread untuk memulihkan afinitas utas sebelumnya. Sering kali, KeSetSystemGroupAffinityThread menulis nilai ke struktur ini yang bukan afinitas grup yang valid tetapi memiliki arti khusus untuk KeRevertToUserGroupAffinityThread. Jangan berikan pointer ke nilai khusus ini sebagai parameter Afinitas dalam panggilan KeSetSystemGroupAffinityThread berikutnya.

Jika perlu, penelepon dapat mengubah afinitas utas lebih dari sekali dengan memanggil KeSetSystemGroupAffinityThread beberapa kali. Selama panggilan pertama ini, pemanggil harus menentukan nilai non-NULL untuk PreviousAffinity sehingga afinitas utas asli dapat ditangkap dan kemudian dipulihkan. Namun, panggilan selanjutnya ke KeSetSystemGroupAffinityThread dapat, sebagai opsi, mengatur PreviousAffinity = NULL. Untuk informasi selengkapnya, lihat Keterangan.

Mengembalikan nilai

Tidak ada

Keterangan

Rutinitas ini mengubah nomor grup dan masker afinitas relatif grup dari utas panggilan. Parameter Afinitas menunjuk ke struktur GROUP_AFFINITY . Nomor grup dan masker afinitas dalam struktur ini mengidentifikasi sekumpulan prosesor tempat utas dapat berjalan. Jika berhasil, rutinitas menjadwalkan utas untuk berjalan pada prosesor dalam set ini.

Jika parameter PreviousAffinity bukan NULL, rutin menyimpan informasi tentang afinitas grup sebelumnya, yang berlaku pada awal panggilan, dalam struktur GROUP_AFFINITY yang dirujuk PreviousAffinity . Untuk memulihkan afinitas utas sebelumnya, pemanggil dapat menyediakan penunjuk ke struktur ini sebagai parameter input ke rutinitas KeRevertToUserGroupAffinityThread .

Dalam sistem multiprosem, rutinitas driver mode kernel yang berjalan dalam konteks utas mode pengguna mungkin perlu memanggil KeSetSystemGroupAffinityThread untuk mengubah afinitas grup utas untuk sementara waktu. Sebelum rutin keluar, harus memanggil KeRevertToUserGroupAffinityThread untuk memulihkan masker afinitas utas ke nilai aslinya.

Proses dapat memiliki afinitas untuk lebih dari satu grup pada satu waktu. Namun, utas hanya dapat ditetapkan ke satu grup kapan saja. Grup itu selalu dalam afinitas proses utas. Utas dapat mengubah grup yang ditetapkan dengan memanggil KeSetSystemGroupAffinityThread.

KeSetSystemGroupAffinityThread mengubah nomor grup dan masker afinitas ke nilai yang ditentukan dalam *Afinitas hanya jika berikut ini benar:

  • Nomor grup valid.
  • Masker afinitas valid (yaitu, hanya bit mask yang sesuai dengan prosesor logis dalam grup yang diatur).
  • Setidaknya salah satu prosesor yang ditentukan dalam masker afinitas aktif.
Jika salah satu kondisi ini tidak terpenuhi, nomor grup dan masker afinitas utas tetap tidak berubah. Jika PreviousAffinity bukan NULL, rutinitas menulis nol ke nomor grup dan masker afinitas di **PreviousAffinity*.

Selain itu, KeSetSystemGroupAffinityThread menulis nol ke nomor grup dan masker afinitas di *PreviousAffinity jika afinitas grup sebelumnya ditetapkan ke utas dalam mode pengguna. Menanggapi struktur GROUP_AFFINITY di mana nomor grup dan masker afinitas keduanya nol, KeRevertToUserGroupAffinityThread memulihkan afinitas utas mode pengguna saat ini. Jika afinitas utas mode pengguna berubah antara panggilan KeSetSystemGroupAffinityThread dan KeRevertToUserGroupAffinityThread , afinitas mode pengguna terbaru ditetapkan ke utas. (Aplikasi dapat memanggil fungsi seperti SetThreadGroupAffinity untuk mengubah afinitas grup mode pengguna dari utas.)

Sebelum masker afinitas baru di *Afinitas berlaku, KeSetSystemGroupAffinityThread menghapus (diatur ke nol) bit mask afinitas apa pun yang sesuai dengan prosesor yang saat ini tidak aktif. Dalam panggilan KeSetSystemGroupAffinityThread berikutnya, nilai yang ditulis rutin ke *PreviousAffinity mungkin berisi masker afinitas yang telah dimodifikasi dengan cara ini.

Rutinitas terkait, KeSetSystemAffinityThreadEx, mengubah masker afinitas utas panggilan, tetapi rutinitas ini, tidak seperti KeSetSystemGroupAffinityThread, tidak menerima nomor grup sebagai parameter input. Dimulai dengan Windows 7, KeSetSystemAffinityThreadEx mengasumsikan bahwa masker afinitas mengacu pada prosesor di grup 0, yang kompatibel dengan perilaku rutinitas ini di versi Windows sebelumnya yang tidak mendukung grup. Perilaku ini memastikan bahwa driver yang ada yang memanggil KeSetSystemAffinityThreadEx dan yang tidak menggunakan fitur berorientasi grup akan berjalan dengan benar dalam sistem multiprosedur yang memiliki dua grup atau lebih. Namun, driver yang menggunakan fitur berorientasi grup apa pun di Windows 7 dan versi yang lebih baru dari sistem operasi Windows harus memanggil KeSetSystemGroupAffinityThread alih-alih KeSetSystemAffinityThreadEx.

KeSetSystemGroupAffinityThread dan KeRevertToUserGroupAffinityThread mendukung berbagai pola panggilan. Dua contoh diperlihatkan dalam diagram berikut.

Diagram berikut mewakili utas driver yang memanggil KeSetSystemGroupAffinityThread tiga kali untuk mengubah afinitas utas, lalu memanggil KeRevertToUserGroupAffinityThread untuk memulihkan afinitas utas asli.

Diagram yang mengilustrasikan beberapa panggilan untuk mengatur afinitas.

Dalam diagram sebelumnya, tiga kotak berlabel "Atur afinitas" adalah panggilan ke KeSetSystemGroupAffinityThread, dan kotak berlabel "Kembalikan afinitas" adalah panggilan ke KeRevertToUserGroupAffinityThread. Panggilan KeSetSystemGroupAffinityThread pertama menggunakan penunjuk output PreviousAffinity untuk menyimpan afinitas utas asli. Dalam dua panggilan berikutnya ke KeSetSystemGroupAffinityThread (ditandai dengan tanda bintang), pemanggil mengatur PreviousAffinity ke NULL. Sebelum utas keluar, ia memanggil KeRevertToUserGroupAffinityThread untuk memulihkan afinitas utas yang disimpan oleh panggilan KeSetSystemGroupAffinityThread pertama.

Diagram berikut menunjukkan pola panggilan yang agak berbeda di mana pasangan panggilan KeSetSystemGroupAffinityThread dan KeRevertToUserGroupAffinityThread ditumpuk. Dalam diagram ini, setiap panggilan ke KeSetSystemGroupAffinityThread di utas driver menggunakan parameter output PreviousAffinity untuk menyimpan afinitas utas sebelumnya, dan masing-masing panggilan ini dipasangkan dengan panggilan ke KeRevertToUserGroupAffinityThread yang memulihkan afinitas utas yang disimpan.

Diagram yang mengilustrasikan panggilan berlapis untuk mengatur dan memulihkan afinitas.

Dalam diagram sebelumnya, fungsi A di utas driver memanggil fungsi B dua kali. Asumsikan bahwa pada entri ke fungsi A, utas masih memiliki afinitas yang ditetapkan untuk itu oleh aplikasi mode pengguna. Dengan demikian, panggilan KeSetSystemGroupAffinityThread dalam fungsi A menyimpan afinitas utas mode pengguna asli. Selama panggilan pertama ke fungsi B, KeSetSystemGroupAffinityThread menyimpan afinitas utas yang ditetapkan oleh driver dalam fungsi A, dan panggilan yang sesuai ke KeRevertToUserGroupAffinityThread memulihkan afinitas ini. Setelah B kembali, KeRevertToUserGroupAffinityThread di A memulihkan afinitas utas asli mode pengguna. Selama panggilan kedua ke B, panggilan KeSetSystemGroupAffinityThread menyimpan afinitas utas asli mode pengguna, dan panggilan yang sesuai ke KeRevertToUserGroupAffinityThread memulihkan afinitas ini. Inti dari contoh ini adalah bahwa fungsi B tidak perlu mengetahui apakah pemanggil (fungsi A) mengubah afinitas utas menjadi nilai yang ditentukan driver sebelum memanggil B.

Jika KeSetSystemGroupAffinityThread dipanggil di IRQL <= APC_LEVEL dan panggilan berhasil, afinitas grup baru segera berlaku. Saat panggilan kembali, utas panggilan sudah berjalan pada prosesor yang ditentukan dalam afinitas grup baru. Jika KeSetSystemGroupAffinityThread dipanggil di IRQL = DISPATCH_LEVEL dan panggilan berhasil, perubahan prosesor yang tertunda ditangguhkan hingga pemanggil menurunkan IRQL di bawah DISPATCH_LEVEL.

Dimulai dengan Windows 11 dan Windows Server 2022, pada sistem dengan lebih dari 64 prosesor, proses dan afinitas utas mencakup semua prosesor dalam sistem, di semua grup prosesor, secara default. Untuk mengatur afinitas grup sistem utas melalui beberapa grup prosesor, gunakan PsSetSystemMultipleGroupAffinityThread.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Tersedia dimulai dengan Windows 7.
Target Platform Universal
Header wdm.h (termasuk Wdm.h, Wdm.h, Ntifs.h)
Pustaka NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL (lihat bagian Keterangan).
Aturan kepatuhan DDI HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

Lihat juga

GROUP_AFFINITY

KeRevertToUserGroupAffinityThread

KeSetSystemAffinityThreadEx

PsSetSystemMultipleGroupAffinityThread