Bagikan melalui

Fungsi MsgWaitForMultipleObjects (winuser.h)

  • Artikel

Menunggu hingga satu atau semua objek yang ditentukan berada dalam status tersinyalir atau interval waktu habis berlalu. Objek dapat menyertakan objek peristiwa input, yang Anda tentukan menggunakan parameter dwWakeMask.

Untuk memasukkan status tunggu yang dapat diperingatkan, gunakan fungsi MsgWaitForMultipleObjectsEx.

Sintaksis

DWORD MsgWaitForMultipleObjects(
  [in] DWORD        nCount,
  [in] const HANDLE *pHandles,
  [in] BOOL         fWaitAll,
  [in] DWORD        dwMilliseconds,
  [in] DWORD        dwWakeMask
);

Parameter

[in] nCount

Jumlah handel objek dalam array yang ditujukkan oleh pHandles. Jumlah maksimum handel objek MAXIMUM_WAIT_OBJECTS dikurangi satu. Jika parameter ini memiliki nilai nol, maka fungsi hanya menunggu peristiwa input.

[in] pHandles

Array handel objek. Untuk daftar tipe objek yang handelnya dapat ditentukan, lihat bagian Keterangan berikut ini. Array dapat berisi handel objek dari berbagai jenis. Ini mungkin tidak berisi beberapa salinan handel yang sama.

Jika salah satu handel ini ditutup saat penantian masih tertunda, perilaku fungsi tidak terdefinisi.

Handel harus memiliki akses SYNCHRONIZE yang tepat. Untuk informasi selengkapnya, lihat Hak Akses Standar.

[in] fWaitAll

Jika parameter ini TRUE, fungsi akan kembali ketika status semua objek dalam pHandles array telah diatur ke sinyal dan peristiwa input telah diterima. Jika parameter ini FALSE, fungsi akan kembali ketika status salah satu objek diatur ke sinyal atau peristiwa input telah diterima. Dalam hal ini, nilai pengembalian menunjukkan objek yang statusnya menyebabkan fungsi dikembalikan.

[in] dwMilliseconds

Interval waktu habis, dalam milidetik. Jika nilai bukan nol ditentukan, fungsi menunggu hingga objek yang ditentukan diberi sinyal atau interval berlalu. Jika dwMilliseconds nol, fungsi tidak memasukkan status tunggu jika objek yang ditentukan tidak diberi sinyal; selalu kembali segera. Jika dwMillisecondsINFINITE, fungsi hanya akan kembali ketika objek yang ditentukan diberi sinyal.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008, dan Windows Server 2008 R2: Nilai dwMilliseconds mencakup waktu yang dihabiskan dalam status berdaya rendah. Misalnya, waktu habis terus menghitung mundur saat komputer tertidur.

Windows 8 dan yang lebih baru, Windows Server 2012 dan yang lebih baru: nilai dwMilliseconds tidak termasuk waktu yang dihabiskan dalam status berdaya rendah. Misalnya, batas waktu tidak terus menghitung mundur saat komputer tertidur.

[in] dwWakeMask

Jenis input tempat handel objek peristiwa input akan ditambahkan ke array handel objek. Parameter ini dapat berupa kombinasi nilai apa pun yang tercantum dalam benderaGetQueueStatus parameter.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian menunjukkan peristiwa yang menyebabkan fungsi dikembalikan. Ini bisa menjadi salah satu nilai berikut. (Perhatikan bahwa WAIT_OBJECT_0 didefinisikan sebagai 0 dan WAIT_ABANDONED_0 didefinisikan sebagai 0x00000080L.)

Mengembalikan kode/nilai Deskripsi
WAIT_OBJECT_0 ke (WAIT_OBJECT_0 + nCount– 1)
 Jika bWaitAllTRUE, nilai pengembalian dalam rentang yang ditentukan menunjukkan bahwa status semua objek yang ditentukan diberi sinyal. Jika bWaitAllFALSE, nilai pengembalian dikurangi WAIT_OBJECT_0 menunjukkan pHandles indeks array objek yang memenuhi penantian.
WAIT_OBJECT_0nCount
 Input baru dari jenis yang ditentukan dalam parameter dwWakeMask tersedia dalam antrean input utas. Fungsi seperti PeekMessage, GetMessage, dan WaitMessage menandai pesan dalam antrean sebagai pesan lama. Oleh karena itu, setelah Anda memanggil salah satu fungsi ini, panggilan berikutnya ke MsgWaitForMultipleObjects tidak akan kembali sampai input baru dari jenis yang ditentukan tiba.

Nilai ini juga dikembalikan setelah terjadinya peristiwa sistem yang memerlukan tindakan utas, seperti aktivasi latar depan. Oleh karena itu, MsgWaitForMultipleObjects dapat kembali meskipun tidak ada input yang sesuai yang tersedia dan bahkan jika dwWakeMask diatur ke 0. Jika ini terjadi, panggil GetMessage atau PeekMessage untuk memproses peristiwa sistem sebelum mencoba panggilan ke MsgWaitForMultipleObjects lagi.
WAIT_ABANDONED_0 ke (WAIT_ABANDONED_0 + nCount– 1)
 Jika bWaitAllTRUE, nilai pengembalian dalam rentang yang ditentukan menunjukkan bahwa status semua objek yang ditentukan diberi sinyal dan setidaknya salah satu objek adalah objek mutex yang ditinggalkan. Jika bWaitAllFALSE, nilai pengembalian dikurangi WAIT_ABANDONED_0 menunjukkan pHandles indeks array objek mutex yang ditinggalkan yang memenuhi penantian. Kepemilikan objek mutex diberikan ke utas panggilan, dan mutex diatur ke nonsignaled.

Jika mutex melindungi informasi status persisten, Anda harus memeriksanya untuk konsistensi.
WAIT_TIMEOUT
258L
 Interval waktu habis berlalu dan kondisi yang ditentukan oleh parameter bWaitAll dan dwWakeMask tidak terpenuhi.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 Fungsi telah gagal. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

Fungsi MsgWaitForMultipleObjects menentukan apakah kriteria tunggu telah terpenuhi. Jika kriteria belum terpenuhi, utas panggilan memasuki status tunggu hingga kondisi kriteria tunggu terpenuhi atau interval waktu habis berlalu.

Ketika bWaitAllTRUE, fungsi tidak mengubah status objek yang ditentukan sampai status semua objek telah diatur ke sinyal. Misalnya, muteks dapat disinyalir, tetapi utas tidak mendapatkan kepemilikan sampai status objek lain juga telah diatur ke sinyal. Sementara itu, beberapa utas lain mungkin mendapatkan kepemilikan mutex, sehingga mengatur statusnya ke nonsignaled.

Ketika bWaitAllTRUE, penantian fungsi selesai hanya ketika status semua objek telah diatur ke sinyal dan peristiwa input telah diterima. Oleh karena itu, pengaturan bWaitAll ke TRUE mencegah input diproses hingga status semua objek dalam pHandles array telah diatur ke sinyal. Untuk alasan ini, jika Anda mengatur bWaitAll ke TRUE, Anda harus menggunakan nilai batas waktu singkat dalam dwMilliseconds. Jika Anda memiliki utas yang membuat jendela menunggu semua objek dalam array pHandles , termasuk peristiwa input yang ditentukan oleh dwWakeMask, tanpa interval waktu habis, sistem akan mengalami kebuntuan. Ini karena utas yang membuat jendela harus memproses pesan. DDE mengirim pesan ke semua jendela dalam sistem. Oleh karena itu, jika utas membuat jendela, jangan atur parameter bWaitAll ke TRUE dalam panggilan ke MsgWaitForMultipleObjects yang dibuat dari utas tersebut.

Ketika bWaitAllFALSE, fungsi ini memeriksa handel dalam array secara berurutan dimulai dengan indeks 0, hingga salah satu objek diberi sinyal. Jika beberapa objek menjadi sinyal, fungsi mengembalikan indeks handel pertama dalam array yang objeknya diberi sinyal.

MsgWaitForMultipleObjects tidak kembali jika ada input yang belum dibaca dari jenis yang ditentukan dalam antrean pesan setelah utas memanggil fungsi untuk memeriksa antrean. Ini karena fungsi seperti PeekMessage, GetMessage, GetQueueStatus, dan WaitMessage memeriksa antrean lalu mengubah informasi status untuk antrean sehingga input tidak lagi dianggap baru. Panggilan berikutnya ke MsgWaitForMultipleObjects tidak akan kembali sampai input baru dari jenis yang ditentukan tiba. Input belum dibaca yang ada (diterima sebelum terakhir kali utas memeriksa antrean) diabaikan.

Fungsi memodifikasi status beberapa jenis objek sinkronisasi. Modifikasi hanya terjadi untuk objek atau objek yang status sinyalnya menyebabkan fungsi kembali. Misalnya, jumlah objek semaphore dikurangi satu. Untuk informasi selengkapnya, lihat dokumentasi untuk objek sinkronisasi individual.

Fungsi MsgWaitForMultipleObjects dapat menentukan handel dari salah satu jenis objek berikut dalam array pHandles :

  • Mengubah pemberitahuan
  • Input konsol
  • Peristiwa
  • Pemberitahuan sumber daya memori
  • Mutex
  • Proses
  • Semaphore
  • Benang
  • Timer yang dapat ditunda

Persyaratan

Syarat Nilai
klien minimum yang didukung Windows XP [hanya aplikasi desktop]
server minimum yang didukung Windows Server 2003 [hanya aplikasi desktop]
Platform Target Windows
Header winuser.h (termasuk Windows.h)
Pustaka User32.lib
DLL User32.dll

Lihat juga

MsgWaitForMultipleObjectsEx

Fungsi Sinkronisasi

Fungsi Tunggu