Fungsi FltCancellableWaitForMultipleObjects (fltkernel.h)

Artikel
04/03/2024

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

Sintaks

NTSTATUS FLTAPI FltCancellableWaitForMultipleObjects(
  [in]           ULONG              Count,
  [in]           PVOID []           ObjectArray,
  [in]           WAIT_TYPE          WaitType,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PKWAIT_BLOCK       WaitBlockArray,
  [in]           PFLT_CALLBACK_DATA CallbackData
);

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

Enumerasi dengan nilai WaitAll, yang menunjukkan bahwa semua objek yang ditentukan harus mencapai status sinyal 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 tempat penantian 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 secara 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] CallbackData

Penunjuk ke struktur FLT_CALLBACK_DATA yang mewakili operasi I/O yang dikeluarkan oleh pengguna dan yang dapat dibatalkan oleh pengguna. Parameter ini bersifat opsional dan dapat berupa NULL. Pemanggil harus memastikan bahwa operasi I/O akan tetap valid selama durasi rutinitas ini dan bahwa I/O tidak boleh memiliki set rutin pembatalan (misalnya, fungsi FltSetCancelCompletion tidak boleh dipanggil pada operasi I/O). Perhatikan bahwa CallbackData harus ditahan oleh pemanggil karena tidak dapat diteruskan ke driver tingkat bawah.

Menampilkan nilai

FltCancellableWaitForMultipleObjects 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 juga 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 operasi I/O. Perhatikan bahwa nilai ini dikembalikan hanya jika CallbackData yang sesuai dengan operasi berbasis IRP diteruskan ke FltCancellableWaitForMultipleObjects dan I/O dibatalkan oleh rutinitas seperti FltCancelIo.
STATUS_THREAD_IS_TERMINATING	Penantian terganggu karena aplikasi atau pengguna telah mengakhiri utas.

Nilai yang dikembalikan hanya menunjukkan status tunggu.

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

FltCancellableWaitForMultipleObjects menjalankan operasi tunggu yang dapat dibatalkan pada objek dispatcher. Jika pengguna atau aplikasi mengakhiri utas, atau jika operasi I/O yang terkait dengan utas dibatalkan oleh rutinitas seperti FltCancelIo, penantian dibatalkan.

Rutinitas ini dirancang untuk mendukung Pedoman Penyelesaian/Pembatalan I/O. Tujuan dari panduan ini adalah untuk memungkinkan pengguna menghentikan aplikasi dengan cepat. Ini, pada gilirannya, mengharuskan aplikasi memiliki kemampuan untuk dengan cepat mengakhiri utas yang menjalankan I/O dan 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 operasi I/O sekunder untuk memproses I/O mode pengguna dan secara sinkron menunggu permintaan sekunder selesai. Salah satu cara untuk melakukan ini adalah dengan menyiapkan peristiwa yang akan disinyalkan oleh rutinitas penyelesaian operasi I/O sekunder dan kemudian menunggu peristiwa disinyalkan. Kemudian, untuk melakukan operasi tunggu yang dapat dibatalkan, FltCancellableWaitForMultipleObjects disebut melewati peristiwa yang terkait dengan operasi I/O sekunder, dan operasi I/O mode pengguna asli. Rangkaian menunggu peristiwa disinyalkan dibatalkan jika peristiwa penghentian tertunda terjadi atau jika operasi I/O 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 blok tunggu bawaan yang dapat Anda gunakan untuk menunggu beberapa objek secara bersamaan. Jika memungkinkan, Anda harus menggunakan array bawaan blok tunggu dalam operasi wait-multiple karena tidak ada penyimpanan blok tunggu tambahan yang perlu dialokasikan dan kemudian dibatalkan alokasinya. Namun, jika jumlah objek yang harus Anda tunggu 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. Anda tidak perlu menginisialisasi buffer, dan driver dapat memperlakukannya sebagai struktur buram. Anda dapat membebaskan buffer setelah rutinitas 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 satu atau beberapa elemen dalam parameter ObjectArray diteruskan ke FltCancellableWaitForMultipleObjects mengacu pada muteks. Jika objek dispatcher yang ditunggu adalah mutex, pengiriman APC sama dengan untuk semua objek dispatcher lainnya selama penantian. Namun, setelah FltCancellableWaitForMultipleObjects 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.

Rutinitas FltCancellableWaitForMultipleObjects harus dipanggil di IRQL PASSIVE_LEVEL jika parameter CallbackData mewakili IRP manajer filter yang valid. Jika tidak, 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.

FltCancellableWaitForMultipleObjects akan menegaskan pada build debug jika CallbackData mewakili operasi IRP Filter Manager, tetapi IRP dalam struktur CallbackData adalah NULL.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista
Target Platform	Universal
Header	fltkernel.h (termasuk Ntifs.h, Fltkernel.h)
Pustaka	Fltmgr.lib
IRQL	Lihat bagian Keterangan.