Fungsi RegisterWaitForSingleObject (winbase.h)
Mengarahkan utas tunggu di kumpulan utas untuk menunggu pada objek. Utas tunggu mengantrekan fungsi panggilan balik yang ditentukan ke kumpulan utas ketika salah satu hal berikut ini terjadi:
- Objek yang ditentukan dalam status disinyalkan.
- Interval waktu habis berlalu.
Sintaks
BOOL RegisterWaitForSingleObject(
[out] PHANDLE phNewWaitObject,
[in] HANDLE hObject,
[in] WAITORTIMERCALLBACK Callback,
[in, optional] PVOID Context,
[in] ULONG dwMilliseconds,
[in] ULONG dwFlags
);
Parameter
[out] phNewWaitObject
Penunjuk ke variabel yang menerima handel tunggu saat dikembalikan. Perhatikan bahwa handel tunggu tidak dapat digunakan dalam fungsi yang memerlukan handel objek, seperti CloseHandle.
[in] hObject
Handel ke objek . Untuk daftar jenis objek yang handelnya dapat ditentukan, lihat bagian Keterangan berikut ini.
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] Callback
Penunjuk ke fungsi jenis WAITORTIMERCALLBACK yang ditentukan aplikasi yang akan dijalankan saat hObject dalam status disinyalkan, atau dwMilliseconds berlalu. Untuk informasi selengkapnya, lihat WaitOrTimerCallback.
[in, optional] Context
Satu nilai yang diteruskan ke fungsi panggilan balik.
[in] dwMilliseconds
Interval waktu habis, dalam milidetik. Fungsi mengembalikan jika interval berlalu, bahkan jika status objek tidak ditandatangani. Jika dwMilliseconds adalah nol, fungsi menguji status objek dan segera kembali. Jika dwMilliseconds adalah INFINITE, interval waktu habis fungsi tidak pernah berlalu.
[in] dwFlags
Parameter ini bisa menjadi satu atau beberapa nilai berikut.
Untuk informasi tentang menggunakan nilai-nilai ini dengan objek yang tetap diberi sinyal, lihat bagian Keterangan.
| Nilai | Makna |
|---|---|
|
Secara default, fungsi panggilan balik diantrekan ke utas pekerja non-I/O. |
|
Bendera ini tidak digunakan.
Windows Server 2003 dan Windows XP: Fungsi panggilan balik diantrekan ke utas pekerja I/O. Bendera ini harus digunakan jika fungsi harus dijalankan dalam utas yang menunggu dalam status yang dapat diperingatkan. Utas pekerja I/O dihapus dimulai dengan Windows Vista dan Windows Server 2008. |
|
Fungsi panggilan balik diantrekan ke utas yang tidak pernah berakhir. Ini tidak menjamin bahwa utas yang sama digunakan setiap kali. Bendera ini harus digunakan hanya untuk tugas pendek atau dapat memengaruhi operasi tunggu lainnya.
Bendera ini harus diatur jika utas memanggil fungsi yang menggunakan APC. Untuk informasi selengkapnya, lihat Panggilan Prosedur Asinkron. Perhatikan bahwa saat ini tidak ada utas pekerja yang benar-benar persisten, meskipun tidak ada utas pekerja yang akan berakhir jika ada permintaan I/O yang tertunda. |
|
Fungsi panggilan balik dipanggil oleh utas tunggu itu sendiri. Bendera ini harus digunakan hanya untuk tugas pendek atau dapat memengaruhi operasi tunggu lainnya.
Kebuntuan dapat terjadi jika beberapa utas lain memperoleh kunci eksklusif dan memanggil fungsi UnregisterWait atau UnregisterWaitEx saat fungsi panggilan balik mencoba memperoleh kunci yang sama. |
|
Fungsi panggilan balik dapat melakukan penantian panjang. Bendera ini membantu sistem untuk memutuskan apakah harus membuat utas baru. |
|
Utas tidak akan lagi menunggu pada handel setelah fungsi panggilan balik dipanggil sekali. Jika tidak, timer direset setiap kali operasi tunggu selesai sampai operasi tunggu dibatalkan. |
|
Fungsi panggilan balik akan menggunakan token akses saat ini, baik itu token proses atau peniruan. Jika bendera ini tidak ditentukan, fungsi panggilan balik hanya dijalankan dengan token proses.
Windows XP: Bendera ini tidak didukung sampai Windows XP dengan SP2 dan Windows Server 2003. |
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan bukan nol.
Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, panggil
GetLastError.
Keterangan
Utas tunggu baru dibuat secara otomatis jika diperlukan. Operasi tunggu dilakukan oleh utas tunggu dari kumpulan utas. Rutinitas panggilan balik dijalankan oleh utas pekerja ketika status objek menjadi sinyal atau interval waktu habis berlalu. Jika dwFlags tidak WT_EXECUTEONLYONCE, timer direset setiap kali peristiwa disinyalkan atau interval waktu habis berlalu.
Ketika penantian selesai, Anda harus memanggil fungsi UnregisterWait atau UnregisterWaitEx untuk membatalkan operasi tunggu. (Operasi tunggu genap yang menggunakan WT_EXECUTEONLYONCE harus dibatalkan.) Jangan melakukan panggilan pemblokiran ke salah satu fungsi ini dari dalam fungsi panggilan balik.
Perhatikan bahwa Anda tidak boleh mengurai objek peristiwa yang diteruskan ke RegisterWaitForSingleObject, karena utas tunggu mungkin tidak mendeteksi bahwa peristiwa tersebut diberi sinyal sebelum diatur ulang. Anda tidak boleh mendaftarkan objek yang tetap diberi sinyal (seperti peristiwa reset manual atau proses yang dihentikan) kecuali Anda mengatur bendera WT_EXECUTEONLYONCE atau WT_EXECUTEINWAITTHREAD . Untuk bendera lain, fungsi panggilan balik mungkin dipanggil terlalu banyak sebelum peristiwa direset.
Fungsi memodifikasi status beberapa jenis objek sinkronisasi. Modifikasi hanya terjadi untuk objek yang status sinyalnya menyebabkan kondisi tunggu terpenuhi. Misalnya, jumlah objek semaphore berkurang satu.
Fungsi RegisterWaitForSingleObject dapat menunggu objek berikut:
- Mengubah pemberitahuan
- Input konsol
- Kejadian
- Pemberitahuan sumber daya memori
- Mutex
- Proses
- Semaphore
- Rangkaian
- Timer yang dapat ditunda
Secara default, kumpulan utas memiliki maksimum 500 utas. Untuk menaikkan batas ini, gunakan makro WT_SET_MAX_THREADPOOL_THREAD yang ditentukan dalam WinNT.h.
#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
((Flags)|=(Limit)<<16)
Gunakan makro ini ketika menentukan parameter dwFlags . Parameter makro adalah bendera yang diinginkan dan batas baru (hingga (2<<16)-1 utas). Namun, perhatikan bahwa aplikasi Anda dapat meningkatkan performanya dengan menjaga jumlah utas pekerja tetap rendah.
Item kerja dan semua fungsi yang dipanggilnya harus aman untuk kumpulan utas. Oleh karena itu, Anda tidak dapat memanggil panggilan asinkron yang memerlukan utas persisten, seperti fungsi RegNotifyChangeKeyValue , dari lingkungan panggilan balik default. Sebagai gantinya, atur kumpulan utas maksimum yang sama dengan minimum kumpulan utas menggunakan fungsi SetThreadpoolThreadMaximum dan SetThreadpoolThreadMinimum , atau buat utas Anda sendiri menggunakan fungsi CreateThread . (Untuk API kumpulan utas asli, tentukan WT_EXECUTEINPERSISTENTTHREAD menggunakan fungsi QueueUserWorkItem .)
Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0500 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winbase.h (termasuk Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk