Bagikan melalui

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.

Sintaksis

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

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 disinyalir atau interval berlalu. Jika dwMilliseconds nol, fungsi tidak memasuki status tunggu jika objek tidak diberi sinyal; selalu kembali segera. Jika dwMillisecondsINFINITE, fungsi akan kembali hanya ketika objek 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.

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 status mutex diatur ke nonsignaled.

Jika mutex melindungi informasi status persisten, Anda harus memeriksanya untuk konsistensi.
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 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
  • 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 dengan interval waktu habis INFINITE 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 WaitForSingleObject.

Contoh

Misalnya, lihat Menggunakan Objek Mutex.

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

  • Last updated on