Bagikan melalui

Fungsi WaitForMultipleObjects (synchapi.h)

Menunggu hingga satu atau semua objek yang ditentukan berada dalam status tersinyalir atau interval waktu habis berlalu.

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

Sintaksis

DWORD WaitForMultipleObjects(
  [in] DWORD        nCount,
  [in] const HANDLE *lpHandles,
  [in] BOOL         bWaitAll,
  [in] DWORD        dwMilliseconds
);

Parameter

[in] nCount

Jumlah handel objek dalam array yang ditujukkan oleh lpHandles. Jumlah maksimum handel objek MAXIMUM_WAIT_OBJECTS. Parameter ini tidak boleh nol.

[in] lpHandles

Array handel objek. Untuk daftar tipe objek yang handelnya dapat ditentukan, lihat bagian Keterangan berikut ini. Array dapat berisi handel ke 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] bWaitAll

Jika parameter ini TRUE, fungsi akan kembali saat status semua objek dalam lpHandles array diberi sinyal. Jika FALSE, fungsi akan kembali saat status salah satu objek diatur ke sinyal. Dalam kasus terakhir, 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.

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 lpHandles indeks array objek yang memenuhi penantian. Jika lebih dari satu objek menjadi sinyal selama panggilan, ini adalah indeks array objek yang disinyalir dengan nilai indeks terkecil dari semua objek yang disinyalir.
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 lpHandles 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
0x00000102L
 Interval waktu habis berlalu dan kondisi yang ditentukan oleh parameter bWaitAll tidak terpenuhi.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 Fungsi telah gagal. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

Fungsi WaitForMultipleObjects 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, operasi tunggu fungsi selesai hanya ketika status semua objek telah diatur ke sinyal. 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 diatur ke sinyal. Sementara itu, beberapa utas lain mungkin mendapatkan kepemilikan mutex, sehingga mengatur statusnya ke nonsignaled.

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.

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.

Untuk menunggu lebih dari MAXIMUM_WAIT_OBJECTS handel, gunakan salah satu metode berikut:

  • Buat utas untuk menunggu handel MAXIMUM_WAIT_OBJECTS, lalu tunggu di utas tersebut ditambah handel lainnya. Gunakan teknik ini untuk memecah handel menjadi grup MAXIMUM_WAIT_OBJECTS.
  • Panggil RegisterWaitForSingleObject atau SetThreadpoolWait untuk menunggu setiap handel. Kumpulan utas menunggu secara efisien pada handel dan menetapkan utas pekerja setelah objek diberi sinyal atau interval waktu habis kedaluwarsa.
Fungsi WaitForMultipleObjects dapat menentukan handel dari salah satu jenis objek berikut dalam array lpHandles:
  • Mengubah pemberitahuan
  • Input konsol
  • Peristiwa
  • Pemberitahuan sumber daya memori
  • Mutex
  • Proses
  • Semaphore
  • Benang
  • Timer yang dapat ditunda
Berhati-hatilah saat memanggil fungsi tunggu dan kode yang secara langsung atau tidak langsung membuat jendela. Jika utas membuat jendela apa pun, utas harus memproses pesan. Siaran pesan dikirim ke semua jendela dalam sistem. Utas yang menggunakan fungsi tunggu tanpa interval waktu habis dapat menyebabkan sistem mengalami kebuntuan. Dua contoh kode yang secara tidak langsung membuat jendela adalah DDE dan fungsi CoInitialize. Oleh karena itu, jika Anda memiliki utas yang membuat jendela, gunakan MsgWaitForMultipleObjects atau MsgWaitForMultipleObjectsEx, daripada WaitForMultipleObjects.

Contoh

Misalnya, lihat Menunggu Beberapa Objek.

Persyaratan

Syarat Nilai
klien minimum yang didukung Windows XP [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung Windows Server 2003 [aplikasi desktop | Aplikasi UWP]
Platform Target Windows
Header synchapi.h (termasuk Windows.h)
Pustaka Kernel32.lib
DLL Kernel32.dll

Lihat juga

WAIT_ABANDONED_0

Fungsi Sinkronisasi

Fungsi Tunggu

  • Last updated on