Fungsi KeSetCoalescableTimer (wdm.h)

Artikel
02/27/2024

Rutinitas KeSetCoalescableTimer mengatur waktu kedaluwarsa awal dan periode objek timer dan menentukan berapa banyak penundaan yang dapat ditoleransi dalam waktu kedaluwarsa.

Sintaks

BOOLEAN KeSetCoalescableTimer(
  [in, out]      PKTIMER       Timer,
  [in]           LARGE_INTEGER DueTime,
  [in]           ULONG         Period,
  [in]           ULONG         TolerableDelay,
  [in, optional] PKDPC         Dpc
);

Parameter

[in, out] Timer

Penunjuk ke objek timer. Parameter ini menunjuk ke struktur KTIMER , yang merupakan struktur sistem buram yang mewakili objek timer. Objek ini harus telah diinisialisasi sebelumnya oleh rutinitas KeInitializeTimerEx atau KeInitializeTimer .

[in] DueTime

Menentukan waktu absolut atau relatif di mana timer akan kedaluwarsa. Jika nilai parameter DueTime negatif, waktu kedaluwarsa relatif terhadap waktu sistem saat ini. Jika tidak, waktu kedaluwarsa adalah absolut. Waktu kedaluwarsa dinyatakan dalam unit waktu sistem, yaitu interval 100 nanodetik. Waktu kedaluwarsa absolut melacak perubahan apa pun yang dilakukan pada jam sistem. Waktu kedaluwarsa relatif tidak dipengaruhi oleh perubahan jam sistem.

[in] Period

Menentukan interval antara kedaluwarsa timer berkala dalam milidetik. Nilai parameter ini tidak boleh melebihi MAXLONG. Parameter ini bersifat opsional dan dapat diatur ke nol untuk menunjukkan bahwa timer nonperiodic.

[in] TolerableDelay

Menentukan toleransi, dalam milidetik, untuk periode timer yang ditentukan Periode dan untuk interval waktu awal yang ditentukan DueTime . Untuk timer berkala, interval waktu antara dua kedaluwarsa timer berturut-turut akan berada dalam rentang dari (Period - TolerableDelay) hingga (Period + TolerableDelay). Waktu kedaluwarsa awal akan berada dalam rentang dari DueTime hingga (DueTime + TolerableDelay). Nilai TolerableDelay tidak boleh negatif.

[in, optional] Dpc

Penunjuk ke objek DPC. Parameter ini menunjuk ke struktur KDPC , yang merupakan struktur sistem buram yang mewakili objek DPC. Objek ini sebelumnya harus diinisialisasi oleh rutinitas KeInitializeDpc . Parameter ini bersifat opsional dan dapat ditentukan sebagai NULL jika pemanggil tidak memerlukan DPC.

Mengembalikan nilai

KeSetCoalescableTimer mengembalikan TRUE jika objek timer sudah berada dalam antrean timer sistem. Jika tidak, ia mengembalikan FALSE.

Keterangan

Rutinitas ini melakukan hal berikut:

Mengatur timer ke status tidak diberi sinyal.
Mengaitkan timer dengan DPC, jika DPC ditentukan.
Membatalkan timer jika sudah aktif.
Membuat timer aktif dan mengatur waktu jatuh tempo dan periode timer ke nilai yang ditentukan. Timer dapat segera kedaluwarsa jika waktu jatuh tempo yang ditentukan telah berlalu.

Rutinitas KeSetTimerEx mirip dengan KeSetCoalescableTimer tetapi tidak menerima parameter TolerableDelay . Parameter TolerableDelay dari KeSetCoalescableTimer memungkinkan pemanggil menentukan toleransi untuk periode timer. Panggilan ke KeSetCoalescableTimer dengan TolerableDelay = 0 sama dengan panggilan ke KeSetTimerEx. Dalam banyak kasus, pengembang dapat dengan mudah memodifikasi driver yang ada dengan mengganti panggilan ke KeSetTimerEx dengan panggilan ke KeSetCoalescableTimer.

Jika dua panggilan KeSetCoalescableTimer menentukan objek timer yang sama, dan panggilan kedua terjadi sebelum DueTime yang ditentukan untuk panggilan pertama kedaluwarsa, panggilan kedua secara implisit membatalkan timer dari panggilan pertama. Namun, jika timer kedaluwarsa dari panggilan pertama telah mengaktifkan DPC untuk dijalankan, DPC mungkin berjalan setelah timer dibatalkan. Panggilan kedua menggantikan waktu kedaluwarsa yang tertunda dari panggilan pertama dengan waktu kedaluwarsa baru, dan mengaktifkan timer lagi.

Jika parameter Periode bukan nol, timer berkala. Untuk timer berkala, kedaluwarsa timer pertama terjadi pada saat yang ditunjukkan oleh parameter DueTime . Kedaluwarsa selanjutnya dipisahkan oleh interval yang ditentukan oleh Periode. Jika Periode = 0, timer nonperiodic dan kedaluwarsa pada saat yang ditunjukkan oleh DueTime.

Jika parameter Dpc bukan NULL, rutinitas membuat hubungan antara objek DPC yang ditentukan dan objek timer. Setelah timer kedaluwarsa, layanan timer menghapus objek timer dari antrean timer sistem dan mengatur objek ini ke status sinyal. Jika objek DPC dikaitkan dengan objek timer, layanan timer menyisipkan objek DPC ke dalam antrean DPC sistem untuk berjalan segera setelah kondisi memungkinkan.

Hanya satu instans objek DPC tertentu yang dapat berada dalam antrean DPC sistem pada satu waktu. Untuk menghindari potensi kondisi balapan, hindari meneruskan objek DPC yang sama ke rutinitas KeSetCoalescableTimer dan KeInsertQueueDpc .

Hindari mengubah kepentingan atau prosesor target DPC yang terkait dengan timer aktif. Batalkan timer atau pastikan timer telah kedaluwarsa sebelum Anda memanggil rutinitas seperti KeSetImportanceDpc atau KeSetTargetProcessorDpcEx untuk mengubah pengaturan DPC. Misalnya, jika driver memperbarui prosesor target DPC sementara timer memungkinkan DPC berjalan, DPC mungkin berjalan pada prosesor arbitrer.

Timer berkala secara otomatis dimulai ulang segera setelah kedaluwarsa. Oleh karena itu, dalam sistem multiprosesor, DPC untuk timer berkala mungkin berjalan pada dua prosesor atau lebih secara bersamaan.

Driver harus membatalkan timer aktif apa pun dalam rutinitas Bongkar . Panggil rutinitas KeCancelTimer untuk membatalkan timer. Jika DPC dikaitkan dengan timer yang berkala atau yang mungkin baru saja kedaluwarsa, driver harus menunggu (misalnya, dengan memanggil rutinitas KeFlushQueuedDpcs ) untuk membebaskan DPC dan data terkaitnya sampai semua eksekusi DPC yang tertunda pada semua prosesor selesai.

KeSetCoalescableTimer menggunakan parameter TolerableDelay untuk melakukan coalescing timer. Artinya, rutinitas menyesuaikan waktu kedaluwarsa agar timer bertepatan dengan waktu kedaluwarsa timer perangkat lunak lainnya. Penggalian timer membantu meningkatkan lamanya periode diam sehingga sistem operasi dapat mengurangi konsumsi daya dan meningkatkan efisiensi energi.

Untuk menggunakan timer coalescing secara efektif, penelepon harus menentukan nilai TolerableDelay setidaknya 32 milidetik. Nilai ini sama dengan dua interval jam sistem default 15,6 milidetik. Jika anda bisa, gunakan nilai TolerableDelay yang lebih besar, seperti 100 milidetik.

Cobalah untuk menentukan nilai Periode dan TolerableDelay dalam kelipatan 50 milidetik. Nilai Periode Umum adalah 50, 100, 250, 500, dan 1000 milidetik. Nilai TolerableDelay yang khas adalah 50, 100, 150, dan 250 milidetik.

Biasanya, timer dengan nilai Periode besar dapat menggunakan nilai TolerableDelay yang proporsional besar. Misalnya, timer dengan Periode = 500 milidetik mungkin menggunakan TolerableDelay = 50 milidetik, tetapi timer dengan Periode = 10 detik mungkin menggunakan TolerableDelay = 1 detik.

Waktu kedaluwarsa diukur relatif terhadap jam sistem, dan akurasi yang dapat dideteksi oleh sistem operasi ketika timer kedaluwarsa dibatasi oleh granularitas jam sistem. Untuk informasi selengkapnya, lihat Akurasi Timer.

Untuk informasi selengkapnya tentang objek timer, lihat Objek Timer dan DPC. Untuk informasi selengkapnya tentang koalescing timer, lihat laporan resmi Windows Timer Coalescing di situs web WHDC.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 7.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL