Fungsi WaitOnAddress (synchapi.h)

Artikel
02/13/2024

Menunggu nilai di alamat yang ditentukan berubah.

Sintaks

BOOL WaitOnAddress(
  [in]           volatile VOID *Address,
  [in]           PVOID         CompareAddress,
  [in]           SIZE_T        AddressSize,
  [in, optional] DWORD         dwMilliseconds
);

Parameter

[in] Address

Alamat tempat menunggu. Jika nilai di Address berbeda dari nilai di CompareAddress, fungsi akan segera ditampilkan. Jika nilainya sama, fungsi tidak kembali sampai utas lain dalam proses yang sama menandakan bahwa nilai di Alamat telah berubah dengan memanggil WakeByAddressSingle atau WakeByAddressAll atau batas waktu berlalu, mana yang lebih dulu.

[in] CompareAddress

Penunjuk ke lokasi nilai yang diamati sebelumnya di Alamat. Fungsi mengembalikan ketika nilai di Address berbeda dari nilai di CompareAddress.

[in] AddressSize

Ukuran nilai, dalam byte. Parameter ini dapat berupa 1, 2, 4, atau 8.

[in, optional] dwMilliseconds

Jumlah milidetik untuk menunggu sebelum waktu operasi habis. Jika parameter ini INFINITE, utas menunggu tanpa batas waktu.

Nilai kembali

TRUE jika penantian berhasil. Jika operasi gagal, fungsi akan mengembalikan FALSE. Jika penantian gagal, hubungi GetLastError untuk mendapatkan informasi kesalahan yang diperluas. Secara khusus, jika waktu operasi habis, GetLastError mengembalikan ERROR_TIMEOUT.

Keterangan

Pengembang aplikasi Microsoft Store mungkin perlu mendapatkan synchronization.lib dengan menginstal Windows Software Development Kit (SDK).

Fungsi WaitOnAddress dapat digunakan oleh utas untuk menunggu nilai tertentu berubah dari beberapa nilai yang tidak diinginkan ke nilai lainnya. WaitOnAddress lebih efisien daripada menggunakan fungsi Sleep di dalam perulangan while karena WaitOnAddress tidak mengganggu penjadwal utas. WaitOnAddress juga lebih mudah digunakan daripada objek peristiwa karena tidak perlu membuat dan menginisialisasi peristiwa lalu memastikannya disinkronkan dengan benar dengan nilai . WaitOnAddress tidak terpengaruh oleh kondisi memori rendah, selain berpotensi membangunkan utas lebih awal seperti yang disebutkan di bawah ini.

Setiap utas dalam proses yang sama yang mengubah nilai di alamat tempat utas menunggu harus memanggil WakeByAddressSingle untuk membangunkan satu utas tunggu atau WakeByAddressAll untuk membangunkan semua utas tunggu. Jika WakeByAddressSingle dipanggil, utas tunggu lainnya terus menunggu.

Catatan:WaitOnAddress dijamin akan kembali ketika alamat disinyalir, tetapi juga diizinkan untuk kembali karena alasan lain. Untuk alasan ini, setelah WaitOnAddress mengembalikan pemanggil harus membandingkan nilai baru dengan nilai asli yang tidak diinginkan untuk mengonfirmasi bahwa nilai benar-benar telah berubah. Misalnya, keadaan berikut dapat mengakibatkan bangun utas lebih awal:

Kondisi memori rendah
Bangun sebelumnya pada alamat yang sama telah ditinggalkan
Menjalankan kode pada build sistem operasi yang diperiksa

Contoh

Contoh berikut menunjukkan cara menggunakan WaitOnAddress.

ULONG g_TargetValue; // global, accessible to all threads
ULONG CapturedValue;
ULONG UndesiredValue;

UndesiredValue = 0;
CapturedValue = g_TargetValue;
while (CapturedValue == UndesiredValue) {
      WaitOnAddress(&g_TargetValue, &UndesiredValue, sizeof(ULONG), INFINITE);
      CapturedValue = g_TargetValue;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	synchapi.h (termasuk Windows.h)
Pustaka	Synchronization.lib
DLL	API-MS-Win-Core-Synch-l1-2-0.dll

Lihat juga

WakeByAddressAll

WakeByAddressSingle

Api Vertdll tersedia di enklave VBS

Bagikan melalui