Fungsi KeWaitForSingleObject (wdm.h)

Artikel
02/27/2024

Rutinitas KeWaitForSingleObject menempatkan utas saat ini ke dalam status tunggu hingga objek dispatcher yang diberikan diatur ke status yang disinyalkan atau (opsional) hingga waktu tunggu habis.

Sintaks

NTSTATUS
KeWaitForSingleObject (
    PVOID Object,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout
    );

Parameter

[in] Object

Penunjuk ke objek dispatcher yang diinisialisasi (peristiwa, mutex, semaphore, thread, atau timer) tempat pemanggil memasok penyimpanan. Objek dispatcher harus berada di memori sistem yang tidak disebarkan. Untuk informasi selengkapnya, lihat Keterangan.

[in] WaitReason

Menentukan alasan untuk menunggu. Driver harus menetapkan nilai ini ke Eksekutif, kecuali jika melakukan pekerjaan atas nama pengguna dan berjalan dalam konteks utas pengguna, dalam hal ini harus mengatur nilai ini ke UserRequest.

[in] WaitMode

Menentukan apakah penelepon menunggu di KernelMode atau UserMode. Driver tingkat terendah dan menengah harus menentukan KernelMode. Jika Objek yang diberikan adalah mutex, pemanggil harus menentukan KernelMode.

[in] Alertable

Menentukan nilai Boolean yang TRUE jika penantian dapat diperingatkan dan FALSE sebaliknya.

[in, optional] Timeout

Penunjuk ke nilai waktu habis yang menentukan waktu absolut atau relatif, dalam unit 100 nanodetik, di mana penantian akan selesai.

Nilai positif menentukan waktu absolut, relatif terhadap 1 Januari 1601. Nilai negatif menentukan interval relatif terhadap waktu saat ini. Waktu kedaluwarsa absolut melacak perubahan apa pun dalam waktu sistem; waktu kedaluwarsa relatif tidak terpengaruh oleh perubahan waktu sistem.

Jika Timeout = 0, rutinitas akan kembali tanpa menunggu. Jika penelepon memasok pointer NULL , rutinitas menunggu tanpa batas waktu hingga objek dispatcher diatur ke status sinyal. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Nilai kembali

KeWaitForSingleObject dapat mengembalikan salah satu hal berikut ini.

Makro NT_SUCCESS mengenali semua nilai status ini sebagai nilai "berhasil".

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Objek dispatcher yang ditentukan oleh parameter Object memenuhi waktu tunggu.
STATUS_ALERTED	Penantian terganggu untuk mengirimkan pemberitahuan ke utas panggilan.
STATUS_USER_APC	Penantian terganggu untuk mengirimkan panggilan prosedur asinkron (APC) pengguna ke utas panggilan.
STATUS_TIMEOUT	Waktu habis terjadi sebelum objek diatur ke status bersinyali. Nilai ini dapat dikembalikan ketika kumpulan kondisi tunggu yang ditentukan tidak dapat segera terpenuhi dan Batas waktu diatur ke nol.

Keterangan

Status Objek yang ditentukan saat ini diperiksa untuk menentukan apakah penantian dapat segera terpenuhi. Jika demikian, efek samping yang diperlukan dilakukan pada objek . Jika tidak, utas saat ini dimasukkan ke dalam status menunggu dan utas baru dipilih untuk dieksekusi pada prosesor saat ini.

Parameter yang dapat diperingatkan menentukan kapan utas dapat diperingatkan dan status tunggunya akibatnya dibatalkan. Untuk informasi tambahan, lihat Tunggu dan APC.

Pertimbangan khusus berlaku ketika parameter Objek yang diteruskan ke KeWaitForSingleObject adalah mutex. Jika objek dispatcher yang ditunggu adalah mutex, pengiriman APC sama dengan untuk semua objek dispatcher lainnya selama penantian. Namun, setelah KeWaitForSingleObject kembali dengan STATUS_SUCCESS dan utas benar-benar memegang mutex, hanya APC mode kernel khusus yang dikirimkan. Pengiriman semua APC lainnya, baik mode kernel maupun mode pengguna, dinonaktifkan. Pembatasan pengiriman APC ini berlanjut hingga mutex dirilis.

Objek dispatcher yang ditujukan oleh parameter Objek harus berada di memori sistem yang tidak di-halaman.

Jika parameter WaitMode adalah UserMode, tumpukan kernel dapat ditukar selama penantian. Akibatnya, penelepon tidak boleh mencoba meneruskan parameter pada tumpukan saat memanggil KeWaitForSingleObject menggunakan argumen UserMode . Jika Anda mengalokasikan peristiwa pada tumpukan, Anda harus mengatur parameter WaitMode ke KernelMode.

Sangat penting untuk memeriksa nilai pengembalian KeWaitForSingleObject ketika parameter WaitMode adalah UserMode atau Alertable adalah TRUE, karena KeWaitForSingleObject mungkin kembali lebih awal dengan status STATUS_USER_APC atau STATUS_ALERTED.

Semua penantian jangka panjang yang dapat dibatalkan oleh pengguna harus menunggu UserMode dan Alertable harus diatur ke FALSE.

Jika memungkinkan, Alertable harus diatur ke FALSE dan WaitMode harus diatur ke KernelMode, untuk mengurangi kompleksitas driver. Pengecualian utama untuk ini adalah ketika penantian adalah penantian jangka panjang.

Jika pointer NULL disediakan untuk Timeout, alur panggilan tetap dalam status tunggu hingga Objek diberi sinyal.

Nilai batas waktu nol memungkinkan pengujian serangkaian kondisi tunggu dan untuk performa bersyarat dari efek samping apa pun jika penantian dapat segera terpenuhi, seperti dalam akuisisi mutex.

Interval waktu habis diukur relatif terhadap jam sistem, dan akurasi di mana sistem operasi dapat mendeteksi akhir interval waktu habis dibatasi oleh granularitas jam sistem. Untuk informasi selengkapnya, lihat Akurasi Timer.

Mutex hanya dapat diperoleh secara rekursif waktu MINLONG. Jika batas ini terlampaui, rutinitas akan menimbulkan pengecualian STATUS_MUTANT_LIMIT_EXCEEDED.

Pemanggil KeWaitForSingleObject harus berjalan di IRQL <= DISPATCH_LEVEL. Namun, jika Timeout = NULL atau Timeout != 0, pemanggil harus berjalan di IRQL <= APC_LEVEL dan dalam konteks utas nonarbitrer. Jika Waktu Habis != NULL dan Waktu Habis = 0, pemanggil harus berjalan di IRQL <= DISPATCH_LEVEL.

KeWaitForMutexObject adalah makro yang mengonversi ke KeWaitForSingleObject, yang dapat digunakan sebagai gantinya.

Untuk performa yang lebih baik, gunakan mutex cepat atau mutex yang dijaga. Untuk informasi selengkapnya, lihat Alternatif untuk Objek Mutex.

Untuk informasi selengkapnya tentang objek mutex, lihat Objek Mutex.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Lihat bagian Keterangan.
Aturan kepatuhan DDI	CompleteRequestStatusCheck(wdm), HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), IrpProcessingComplete(wdm), IrqlKeWaitForMutexObject(wdm), LowerDriverReturn(wdm), MarkIrpPending2(wdm), PendedCompletedRequest(wdm), PendedCompletedRequest2(wdm), PendedCompletedRequest3(wdm), PendedCompletedRequestEx(wdm), RemoveLockForwardDeviceControl(wdm), RemoveLockForwardDeviceControlInternal(wdm), RemoveLockForwardRead(wdm), RemoveLockForwardWrite(wdm), SpNoWait(storport), StartDeviceWait(wdm), StartDeviceWait2(wdm), StartDeviceWait3(wdm), StartDeviceWait4(wdm)