Fungsi WaitForSingleObject (synchapi.h)
Menunggu hingga objek yang ditentukan dalam status tersinyal atau interval waktu habis berlalu.
Untuk memasukkan status tunggu yang dapat diperingatkan, gunakan fungsi WaitForSingleObjectEx . Untuk menunggu beberapa objek, gunakan WaitForMultipleObjects.
Sintaks
DWORD WaitForSingleObject(
[in] HANDLE hHandle,
[in] DWORD dwMilliseconds
);
Parameter
[in] hHandle
Handel ke objek . Untuk daftar jenis objek yang handelnya dapat ditentukan, lihat bagian Keterangan berikut.
Jika handel ini ditutup saat penantian masih tertunda, perilaku fungsi tidak terdefinis.
Handel harus memiliki hak akses SYNCHRONIZE . 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 atau interval berlalu. Jika dwMilliseconds adalah nol, fungsi tidak memasuki status tunggu jika objek tidak diberi sinyal; itu selalu segera kembali. Jika dwMilliseconds adalah INFINITE, fungsi hanya akan kembali ketika objek diberi sinyal.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 dan Windows Server 2008 R2: Nilai dwMilliseconds memang mencakup waktu yang dihabiskan dalam status berdaya rendah. Misalnya, waktu habis terus menghitung mundur saat komputer tertidur.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 dan Windows Server 2016: Nilai dwMilliseconds tidak menyertakan waktu yang dihabiskan dalam status berdaya rendah. Misalnya, batas waktu tidak terus menghitung mundur saat komputer tertidur.
Nilai kembali
Jika fungsi berhasil, nilai pengembalian menunjukkan peristiwa yang menyebabkan fungsi dikembalikan. Ini bisa menjadi salah satu nilai berikut.
Mengembalikan kode/nilai | Deskripsi |
---|---|
|
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 status mutex diatur ke nonsignaled.
Jika mutex melindungi informasi status persisten, Anda harus memeriksanya untuk konsistensi. |
|
Status objek yang ditentukan disinyalir. |
|
Interval waktu habis berlalu, dan status objek tidak ditandatangani. |
|
Fungsi telah gagal. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError. |
Keterangan
Fungsi WaitForSingleObject memeriksa status objek yang ditentukan saat ini. Jika status objek tidak ditandatangani, utas panggilan memasuki status tunggu hingga objek diberi sinyal 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 WaitForSingleObject dapat menunggu objek berikut:
- Mengubah pemberitahuan
- Input konsol
- Kejadian
- Pemberitahuan sumber daya memori
- Mutex
- Proses
- Semaphore
- Rangkaian
- Timer yang dapat ditunda
Contoh
Misalnya, lihat Menggunakan Objek Mutex.
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Windows XP [aplikasi desktop | Aplikasi UWP] |
Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
Target Platform | 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 |