Fungsi RegisterWaitForSingleObject (winbase.h)

Artikel
03/03/2024

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
WT_EXECUTEDEFAULT 0x00000000	Secara default, fungsi panggilan balik diantrekan ke utas pekerja non-I/O.
WT_EXECUTEINIOTHREAD 0x00000001	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.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	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.
WT_EXECUTEINWAITTHREAD 0x00000004	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.
WT_EXECUTELONGFUNCTION 0x00000010	Fungsi panggilan balik dapat melakukan penantian panjang. Bendera ini membantu sistem untuk memutuskan apakah harus membuat utas baru.
WT_EXECUTEONLYONCE 0x00000008	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.
WT_TRANSFER_IMPERSONATION 0x00000100	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

Untuk informasi selengkapnya, lihat Objek Sinkronisasi.

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