Fungsi WaitForSingleObjectEx (synchapi.h)

Artikel
11/08/2024

Menunggu hingga objek yang ditentukan dalam status sinyal, rutinitas penyelesaian I/O atau panggilan prosedur asinkron (APC) diantrekan ke utas, atau interval waktu habis berlalu.

Untuk menunggu beberapa objek, gunakan WaitForMultipleObjectsEx.

Sintaksis

DWORD WaitForSingleObjectEx(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

Parameter

[in] hHandle

Handel ke objek. Untuk daftar tipe objek yang handelnya dapat ditentukan, lihat bagian Keterangan berikut ini.

Jika handel ini ditutup saat penantian masih tertunda, perilaku fungsi tidak ditentukan.

Handel harus memiliki akses SINKRONISASI . Untuk informasi selengkapnya, lihat Hak Akses Standar.

[in] dwMilliseconds

Interval waktu habis, dalam milidetik. Jika nilai bukan nol ditentukan, fungsi menunggu hingga objek diberi sinyal, rutinitas penyelesaian I/O atau APC diantrekan, atau interval berlalu. Jika dwMilliseconds nol, fungsi tidak memasukkan status tunggu jika kriteria tidak terpenuhi; selalu kembali segera. Jika dwMillisecondsINFINITE, fungsi akan kembali hanya ketika objek diberi sinyal atau rutinitas penyelesaian I/O atau APC diantrekan.

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] bAlertable

Jika parameter ini TRUE dan utas dalam status tunggu, fungsi akan kembali saat sistem mengantrekan rutinitas penyelesaian I/O atau APC, dan utas menjalankan rutinitas atau fungsi. Jika tidak, fungsi tidak mengembalikan, dan rutinitas penyelesaian atau fungsi APC tidak dijalankan.

Rutinitas penyelesaian diantrekan ketika fungsi ReadFileEx atau WriteFileEx yang telah ditentukan. Fungsi tunggu kembali dan rutinitas penyelesaian hanya dipanggil jika bAlertableTRUE, dan utas panggilan adalah utas yang memulai operasi baca atau tulis. APC diantrekan saat Anda memanggil QueueUserAPC.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian menunjukkan peristiwa yang menyebabkan fungsi dikembalikan. Ini bisa menjadi salah satu nilai berikut.

Mengembalikan kode/nilai	Deskripsi
WAIT_ABANDONED 0x00000080L	Objek yang ditentukan adalah objek mutex yang tidak dirilis oleh utas yang memiliki objek mutex sebelum utas pemilik dihentikan. Kepemilikan objek mutex diberikan ke utas panggilan dan mutex diatur ke nonsignaled. Jika mutex melindungi informasi status persisten, Anda harus memeriksanya untuk konsistensi.
WAIT_IO_COMPLETION 0x000000C0L	Penantian diakhir oleh satu atau beberapa mode pengguna panggilan prosedur asinkron (APC) yang diantrekan ke utas.
WAIT_OBJECT_0 0x00000000L	Status objek yang ditentukan diberi sinyal.
WAIT_TIMEOUT 0x00000102L	Interval waktu habis berlalu, dan status objek tidak ditandatangani.
WAIT_FAILED (DWORD)0xFFFFFFFF	Fungsi telah gagal. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

Fungsi WaitForSingleObjectEx 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.

Fungsi memodifikasi status beberapa jenis objek sinkronisasi. Modifikasi hanya terjadi untuk objek yang status sinyalnya menyebabkan fungsi kembali. Misalnya, jumlah objek semaphore dikurangi satu.

Fungsi WaitForSingleObjectEx dapat menunggu objek berikut:

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 WaitForSingleObjectEx.

Contoh

Misalnya, lihat Server Pipa Bernama Menggunakan Rutinitas Penyelesaian.

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 pada Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

Fungsi Sinkronisasi

Fungsi Tunggu

Bagikan melalui