Fungsi KeWaitForMultipleObjects (wdm.h)

Artikel
02/29/2024

Rutinitas KeWaitForMultipleObjects menempatkan utas saat ini ke dalam status tunggu yang dapat diperingatkan atau tidak dapat diperingatkan hingga salah satu atau semua objek dispatcher diatur ke status tersimpan atau (opsional) hingga waktu tunggu habis.

Sintaks

NTSTATUS
KeWaitForMultipleObjects (
    ULONG Count,
    PVOID Object[],
    WaitType,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout,
    PKWAIT_BLOCK WaitBlockArray
    );

Parameter

[in] Count

Jumlah objek yang akan ditunggu. Parameter ini menentukan jumlah elemen dalam array yang ditujukkan oleh parameter Objek .

[in] Object

Penunjuk ke array pointer untuk mengirimkan objek (peristiwa, mutex, semaphore, utas, dan timer) tempat penelepon memasok penyimpanan. Baik array penunjuk maupun objek dispatcher harus berada di memori sistem yang tidak disebarkan. Untuk informasi selengkapnya, lihat Keterangan.

[in] WaitType

Jenis operasi tunggu yang akan dilakukan. Tentukan WaitAll, yang menunjukkan bahwa semua objek yang ditentukan harus mencapai status bersinyali sebelum penantian terpenuhi; atau WaitAny, menunjukkan bahwa salah satu objek harus mencapai status bersinyali sebelum penantian terpenuhi.

[in] WaitReason

Alasan untuk menunggu. Driver harus mengatur nilai ini ke Eksekutif atau, jika driver melakukan pekerjaan atas nama pengguna dan berjalan dalam konteks utas pengguna, ke UserRequest.

[in] WaitMode

Apakah penelepon menunggu di KernelMode atau UserMode. Driver tingkat menengah dan terendah harus menentukan KernelMode. Jika kumpulan objek yang ditunggu menyertakan mutex, pemanggil harus menentukan KernelMode.

[in] Alertable

Nilai Boolean yang menunjukkan apakah utas dapat diberi tahu saat berada dalam status menunggu.

[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 *Waktu habis = 0, rutinitas akan kembali tanpa menunggu. Jika penelepon memasok penunjuk NULL , rutinitas menunggu tanpa batas waktu sampai salah satu atau semua objek dispatcher diatur ke status yang disinyalir. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[out, optional] WaitBlockArray

Penunjuk ke array KWAIT_BLOCK yang dialokasikan penelepon. Jika Count<= THREAD_WAIT_OBJECTS, maka WaitBlockArray bisa null. Jika tidak, parameter ini harus menunjuk ke buffer memori sizeof(KWAIT_BLOCK) * Hitung byte. Rutinitas menggunakan buffer ini untuk menyimpan rekaman saat melakukan operasi tunggu. Buffer WaitBlockArray harus berada di memori sistem yang tidak disebarkan. Untuk informasi selengkapnya, lihat Keterangan.

Nilai kembali

KeWaitForMultipleObjects dapat mengembalikan salah satu hal berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Pemanggil menentukan WaitAll untuk parameter WaitType dan semua objek dispatcher dalam array Object telah diatur ke status sinyal.
STATUS_ALERTED	Penantian terganggu untuk mengirimkan pemberitahuan ke utas panggilan.
STATUS_USER_APC	Penantian terganggu untuk mengirimkan panggilan prosedur asinkron pengguna (APC) ke utas panggilan.
STATUS_TIMEOUT	Waktu habis terjadi sebelum kumpulan kondisi tunggu yang ditentukan terpenuhi. Nilai ini dapat dikembalikan ketika nilai batas waktu eksplisit nol ditentukan, tetapi serangkaian kondisi tunggu yang ditentukan tidak dapat segera dipenuhi.
STATUS_WAIT_0 melalui STATUS_WAIT_63	Pemanggil menentukan WaitAny untuk WaitType dan salah satu objek dispatcher dalam array Object telah diatur ke status sinyal. Enam bit yang lebih rendah dari nilai yang dikembalikan mengodekan indeks berbasis nol dari objek yang memenuhi penantian.
STATUS_ABANDONED_WAIT_0 melalui STATUS_ABANDONED_WAIT_63	Penelepon mencoba menunggu mutex yang telah ditinggalkan. Enam bit yang lebih rendah dari nilai pengembalian mengodekan indeks berbasis nol dari mutex dalam array Objek .

Perhatikan bahwa makro NT_SUCCESS mengenali semua nilai status ini sebagai nilai "berhasil".

Keterangan

Setiap objek utas memiliki array blok tunggu bawaan yang dapat digunakan untuk menunggu beberapa objek diatur secara bersamaan. Jika memungkinkan, array blok tunggu bawaan harus digunakan dalam operasi wait-multiple karena tidak ada penyimpanan blok tunggu tambahan yang perlu dialokasikan dan kemudian dibatalkan alokasinya. Namun, jika jumlah objek yang harus ditunggu secara bersamaan lebih besar dari jumlah blok tunggu bawaan, gunakan parameter WaitBlockArray untuk menentukan set alternatif blok tunggu yang akan digunakan dalam operasi tunggu. Driver hanya perlu mengalokasikan buffer memori yang cukup besar untuk WaitBlockArray. Buffer tidak perlu diinisialisasi; namun, itu harus dialokasikan dari memori sistem yang tidak disebarkan. Jika parameter WaitMode adalah UserMode, buffer WaitBlockArray tidak boleh dialokasikan pada tumpukan lokal karena tumpukan mungkin ditukar kehabisan memori. Driver dapat memperlakukan buffer ini sebagai struktur buram dan dapat membebaskannya setelah rutin kembali. Jika Count> MAXIMUM_WAIT_OBJECTS atau jika WaitBlockArrayNULL dan Count> THREAD_WAIT_OBJECTS, sistem mengeluarkan Bug Check 0xC (MAXIMUM_WAIT_OBJECTS_EXCEEDED).

Status saat ini untuk setiap objek yang ditentukan diperiksa untuk menentukan apakah penantian dapat segera dipenuhi. Jika efek samping yang diperlukan dilakukan pada objek, nilai yang sesuai dikembalikan.

Jika waktu tunggu tidak dapat segera dipenuhi dan tidak ada nilai waktu habis atau nilai batas waktu nonzero telah ditentukan, utas saat ini dimasukkan ke dalam status menunggu dan utas baru dipilih untuk dieksekusi pada prosesor saat ini. Jika tidak ada Batas Waktu yang disediakan, utas panggilan akan tetap dalam status tunggu hingga kondisi yang ditentukan oleh Object dan WaitType terpenuhi.

Jika Batas Waktu ditentukan, penantian akan otomatis terpenuhi jika tidak ada kondisi tunggu yang ditentukan yang terpenuhi ketika interval yang diberikan kedaluwarsa.

Nilai waktu habis nol memungkinkan pengujian serangkaian kondisi tunggu, secara kondisional melakukan efek samping jika penantian dapat segera terpenuhi, seperti dalam akuisisi mutex.

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

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

Array yang ditujukkan oleh parameter Objek harus berada di memori sistem yang tidak disebarkan. Biasanya, driver mengalokasikan penyimpanan untuk array Objek pada tumpukan lokal. Array Objek dapat dialokasikan pada tumpukan lokal terlepas dari nilai parameter WaitMode.

Objek dispatcher yang ditujukkan oleh elemen dalam array Objek harus berada di memori sistem yang tidak disebarkan. Jika parameter WaitMode adalah UserMode, tumpukan kernel dapat ditukar selama penantian. Akibatnya, penelepon tidak boleh mencoba meneruskan parameter pada tumpukan saat memanggil KeWaitForMultipleObjects dengan argumen UserMode . Jika Anda mengalokasikan peristiwa pada tumpukan, Anda harus mengatur parameter WaitMode ke KernelMode.

Pertimbangan khusus berlaku ketika parameter Objek yang diteruskan ke KeWaitForMultipleObjects adalah mutex. Jika objek dispatcher yang ditunggu adalah mutex, pengiriman APC sama dengan untuk semua objek dispatcher lainnya selama menunggu. Namun, setelah KeWaitForMultipleObjects 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.

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

Semua penantian jangka panjang yang dapat dibatalkan oleh pengguna harus berupa UserMode menunggu 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.

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

Penelepon KeWaitForMultipleObjects dapat 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.)

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 2000.
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	HwStorPortProhibitedDDIs(storport), IrpProcessingComplete(wdm), IrqlKeWaitForMultipleObjects(wdm), SpNoWait(storport)