Fungsi SignalObjectAndWait (synchapi.h)
Memberi sinyal satu objek dan menunggu pada objek lain sebagai operasi tunggal.
Sintaks
DWORD SignalObjectAndWait(
[in] HANDLE hObjectToSignal,
[in] HANDLE hObjectToWaitOn,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parameter
[in] hObjectToSignal
Handel ke objek yang akan disinyalir. Objek ini bisa berupa semaphore, mutex, atau event.
Jika handel adalah semaphore, hak akses SEMAPHORE_MODIFY_STATE diperlukan. Jika handel adalah peristiwa, hak akses EVENT_MODIFY_STATE diperlukan. Jika handel adalah mutex dan pemanggil tidak memiliki mutex, fungsi gagal dengan ERROR_NOT_OWNER.
[in] hObjectToWaitOn
Handel ke objek untuk menunggu. Hak akses SYNCHRONIZE diperlukan; untuk informasi selengkapnya, lihat Keamanan Objek Sinkronisasi dan Hak Akses. Untuk daftar jenis objek yang handelnya bisa Anda tentukan, lihat bagian Keterangan.
[in] dwMilliseconds
Interval waktu habis, dalam milidetik. Fungsi mengembalikan jika interval berlalu, bahkan jika status objek tidak ditandatangani dan tidak ada penyelesaian atau objek panggilan prosedur asinkron (APC) yang diantrekan. Jika dwMilliseconds adalah nol, fungsi menguji status objek, memeriksa rutinitas penyelesaian antrean atau APC, dan segera kembali. Jika dwMilliseconds adalah INFINITE, interval waktu habis fungsi tidak pernah berlalu.
[in] bAlertable
Jika parameter ini TRUE, fungsi akan kembali saat sistem mengantrekan fungsi rutinitas penyelesaian I/O atau APC, dan utas memanggil fungsi . Jika FALSE, fungsi tidak kembali, dan utas tidak memanggil fungsi rutinitas penyelesaian atau APC.
Rutinitas penyelesaian diantrekan ketika panggilan fungsi yang mengantre APC telah selesai. Fungsi ini kembali dan rutinitas penyelesaian dipanggil hanya jika bAlertabletrue, dan utas panggilan adalah utas yang mengantre APC.
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 mutex diatur ke nonsignaled.
Jika mutex melindungi informasi status persisten, Anda harus memeriksanya untuk konsistensi. |
|
Penantian berakhir dengan satu atau beberapa panggilan prosedur asinkron mode pengguna (APC) yang diantrekan ke utas. |
|
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 SignalObjectAndWait menyediakan cara yang lebih efisien untuk memberi sinyal pada satu objek dan kemudian menunggu di objek lain dibandingkan dengan panggilan fungsi terpisah seperti SetEvent diikuti oleh WaitForSingleObject.
Fungsi SignalObjectAndWait dapat menunggu objek berikut:
- Mengubah pemberitahuan
- Input konsol
- Kejadian
- Pemberitahuan sumber daya memori
- Mutex
- Proses
- Semaphore
- Rangkaian
- Timer yang dapat ditunda
Utas dapat menggunakan fungsi SignalObjectAndWait untuk memastikan bahwa utas pekerja dalam status tunggu sebelum memberi sinyal objek. Misalnya, utas dan utas pekerja dapat menggunakan handel ke objek peristiwa untuk menyinkronkan pekerjaan mereka. Utas menjalankan kode seperti berikut:
dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
if( WAIT_OBJECT_0 == dwRet)
SetEvent(hEventMoreWorkToDo);
Utas pekerja menjalankan kode seperti berikut ini:
dwRet = SignalObjectAndWait(hEventWorkerDone,
hEventMoreWorkToDo,
INFINITE,
FALSE);
Perhatikan bahwa "sinyal" dan "tunggu" tidak dijamin akan dilakukan sebagai operasi atomik. Utas yang dijalankan pada prosesor lain dapat mengamati status yang disinyalir dari objek pertama sebelum utas memanggil SignalObjectAndWait memulai penantiannya pada objek kedua.
Berhati-hatilah saat menggunakan SignalObjectAndWait dan PulseEvent dengan Windows 7, karena menggunakan API ini di antara beberapa utas dapat menyebabkan aplikasi mengalami kebuntuan. Utas yang disinyalir oleh SignalObjectAndWait memanggil PulseEvent untuk memberi sinyal objek tunggu panggilan SignalObjectAndWait . Dalam beberapa keadaan, pemanggil SignalObjectAndWait tidak dapat menerima status sinyal objek tunggu tepat waktu, menyebabkan kebuntuan.
Berhati-hatilah saat menggunakan 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 menjadi mengalami kebuntuan. Dua contoh kode yang secara tidak langsung membuat jendela adalah DDE dan COM CoInitialize. Oleh karena itu, jika Anda memiliki utas yang membuat jendela, pastikan untuk memanggil SignalObjectAndWait dari utas yang berbeda. Jika ini tidak memungkinkan, Anda dapat menggunakan MsgWaitForMultipleObjects atau MsgWaitForMultipleObjectsEx, tetapi fungsionalitasnya tidak setara.
Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0400 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.
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) |
| 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