Fungsi FsRtlCancellableWaitForMultipleObjects (ntifs.h)

Artikel
08/07/2023

Rutinitas FsRtlCancellableWaitForMultipleObjects menjalankan operasi tunggu yang dapat dibatalkan (tunggu yang dapat dihentikan) pada satu atau beberapa objek dispatcher.

Sintaks

NTSTATUS FsRtlCancellableWaitForMultipleObjects(
  [in]           ULONG          Count,
  [in]           PVOID []       ObjectArray,
  [in]           WAIT_TYPE      WaitType,
  [in, optional] PLARGE_INTEGER Timeout,
  [in, optional] PKWAIT_BLOCK   WaitBlockArray,
  [in, optional] PIRP           Irp
);

Parameter

[in] Count

Jumlah objek yang akan ditunggu.

[in] ObjectArray

Pointer ke array pointer ke objek dispatcher (peristiwa, mutex, semaphore, thread, dan timer) tempat penelepon memasok penyimpanan.

[in] WaitType

Baik WaitAll, yang menunjukkan bahwa semua objek yang ditentukan harus mencapai status yang disinyalkan sebelum penantian terpenuhi; atau WaitAny, yang menunjukkan bahwa salah satu objek harus mencapai status yang diberi sinyal sebelum penantian terpenuhi.

[in, optional] Timeout

Penunjuk ke nilai batas waktu opsional. Parameter ini menentukan waktu absolut atau relatif, dalam 100 unit nanodetik, di mana penantian akan selesai.

Jika Timeout menunjuk ke nilai nol (yaitu, *Waktu habis == 0), rutinitas akan kembali tanpa menunggu. Jika penelepon menyediakan penunjuk NULL (yaitu, Timeout == NULL), rutin menunggu tanpa batas waktu hingga salah satu atau semua objek dispatcher diatur ke status yang disinyalkan.

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 Batas Waktu ditentukan, penantian akan otomatis terpenuhi jika tidak ada kondisi tunggu yang ditentukan yang terpenuhi saat interval yang diberikan kedaluwarsa.

Nilai batas waktu nol (yaitu, *Waktu habis == 0) memungkinkan Anda untuk menguji serangkaian kondisi tunggu, dan untuk melakukan tindakan tambahan secara kondisional jika penantian dapat segera terpenuhi, seperti dalam akuisisi mutex.

[in, optional] WaitBlockArray

Jika Count<= THREAD_WAIT_OBJECTS, WaitBlockArray bisa null. Jika tidak, parameter ini harus menunjuk ke buffer sizeof(KWAIT_BLOCK * Count) memori byte. Rutinitas menggunakan buffer ini untuk menyimpan rekaman saat melakukan operasi tunggu.

[in, optional] Irp

Penunjuk ke IRP asli yang sesuai dengan operasi I/O yang dikeluarkan oleh pengguna dan yang dapat dibatalkan oleh pengguna. Pemanggil harus memastikan bahwa IRP akan tetap valid selama durasi rutinitas ini dan bahwa IRP tidak boleh memiliki set rutin pembatalan (misalnya, IoSetCancelRoutine tidak boleh dipanggil pada IRP). Perhatikan bahwa IRP harus dipegang oleh pemanggil, tidak dapat diteruskan ke driver tingkat bawah.

Nilai kembali

FsRtlCancellableWaitForMultipleObjects dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Pemanggil menentukan WaitAll untuk parameter WaitType dan semua objek dispatcher dalam array ObjectArray telah diatur ke status sinyal.
STATUS_TIMEOUT	Waktu habis terjadi sebelum kumpulan kondisi tunggu yang ditentukan terpenuhi. Nilai ini dapat dikembalikan ketika kumpulan kondisi tunggu yang ditentukan tidak dapat segera terpenuhi dan Batas waktu diatur ke nol.
STATUS_WAIT_0 melalui STATUS_WAIT_63	Pemanggil menentukan WaitAny untuk WaitType dan salah satu objek dispatcher dalam array ObjectArray telah diatur ke status sinyal. Enam bit bawah dari nilai pengembalian mengodekan indeks berbasis nol dari objek yang memenuhi penantian.
STATUS_ABANDONED_WAIT_0 melalui STATUS_ABANDONED_WAIT_63	Penelepon berusaha menunggu mutex yang telah ditinggalkan. Enam bit bawah dari nilai pengembalian mengodekan indeks berbasis nol dari mutex dalam array ObjectArray .
STATUS_CANCELLED	Penantian terganggu oleh permintaan pembatalan yang tertunda pada IRP yang ditentukan. Perhatikan bahwa nilai ini dikembalikan hanya jika IRP yang valid diteruskan ke FsRtlCancellableWaitForMultipleObjects dan IRP dibatalkan oleh CancelSynchronousIo.
STATUS_THREAD_IS_TERMINATING	Penantian terganggu karena utas telah dihentikan oleh aplikasi atau pengguna.

Nilai yang dikembalikan hanya menunjukkan status tunggu. Jika berlaku, status aktual permintaan I/O harus diperoleh langsung dari IRP lain yang dihasilkan dalam proses penanganan IRP mode pengguna asli.

Perhatikan bahwa makro NT_SUCCESS mengembalikan FALSE ("kegagalan") untuk nilai status STATUS_CANCELLED dan STATUS_THREAD_IS_TERMINATING dan TRUE ("berhasil") untuk semua nilai status lainnya.

Keterangan

Rutinitas FsRtlCancellableWaitForMultipleObjects menjalankan operasi tunggu yang dapat dibatalkan pada objek dispatcher. Jika utas dihentikan oleh pengguna atau oleh aplikasi, atau jika CancelSynchronousIo memposting permintaan pembatalan pada IRP utas (IRP sinkron) yang terkait dengan utas, penantian dibatalkan.

Rutinitas FsRtlCancellableWaitForMultipleObjects dirancang untuk mendukung Panduan Penyelesaian/Pembatalan I/O yang dimulai dengan Windows Vista. Tujuan dari panduan ini adalah untuk memungkinkan pengguna (atau aplikasi) menghentikan aplikasi dengan cepat. Ini, pada gilirannya, mengharuskan aplikasi memiliki kemampuan untuk dengan cepat mengakhiri utas yang menjalankan I/O serta operasi I/O saat ini. Rutinitas ini menyediakan cara bagi utas pengguna untuk memblokir (yaitu, tunggu) di kernel untuk penyelesaian I/O, objek dispatcher, atau variabel sinkronisasi dengan cara yang memungkinkan penantian dibatalkan dengan mudah. Rutinitas ini juga memungkinkan penantian utas dihentikan jika utas dihentikan oleh pengguna atau aplikasi.

Misalnya, pengalih mungkin perlu membuat satu atau beberapa IRP sekunder untuk memproses IRP mode pengguna dan secara sinkron menunggu runtime integrasi sekunder selesai. Salah satu cara untuk melakukan ini adalah dengan menyiapkan peristiwa yang akan disinyalkan oleh rutinitas penyelesaian IRP sekunder dan kemudian menunggu peristiwa disinyalkan. Kemudian, untuk melakukan operasi tunggu yang dapat dibatalkan, FsRtlCancellableWaitForMultipleObjects disebut melewati peristiwa yang terkait dengan IRP sekunder, serta IRP mode pengguna asli. Rangkaian menunggu peristiwa disinyalkan dibatalkan jika peristiwa penghentian tertunda terjadi atau jika IRP mode pengguna asli dibatalkan.

Perhatikan bahwa mengakhiri penantian tidak secara otomatis membatalkan operasi I/O apa pun yang dikeluarkan oleh pemanggil - yang harus ditangani secara terpisah oleh pemanggil.

Setiap objek utas memiliki array bawaan blok tunggu yang dapat digunakan untuk menunggu beberapa objek secara bersamaan. Jika memungkinkan, array bawaan blok tunggu 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 sekumpulan blok tunggu alternatif yang akan digunakan dalam operasi tunggu. Driver hanya perlu mengalokasikan buffer memori yang cukup besar untuk WaitBlockArray. Buffer tidak perlu diinisialisasi, dan driver dapat memperlakukannya sebagai struktur buram. Buffer dapat dibebaskan setelah rutin kembali.

Jika Count lebih besar dari MAXIMUM_WAIT_OBJECTS atau jika WaitBlockArray ADALAH NULL dan Count lebih besar dari THREAD_WAIT_OBJECTS, sistem mengeluarkan Bug Check 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.

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

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

FsRtlCancellableWaitForMultipleObjects harus dipanggil di IRQL PASSIVE_LEVEL jika parameter Irp opsional menunjuk ke IRP yang valid. Jika parameter Irp tidak digunakan, rutinitas dapat dipanggil di IRQL kurang atau sama dengan APC_LEVEL. APC kernel normal dapat dinonaktifkan oleh pemanggil, jika diperlukan, dengan memanggil rutinitas KeEnterCriticalRegion atau FsRtlEnterFileSystem . Namun, APC kernel khusus tidak boleh dinonaktifkan.

FsRtlCancellableWaitForMultipleObjects akan menegaskan pada build debug jika IRQL lebih besar atau sama dengan APC_LEVEL dan parameter Irp menunjuk ke IRP yang valid.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Target Platform	Universal
Header	ntifs.h (termasuk Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Lihat bagian Keterangan.
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm), SpNoWait(storport)