Fungsi SleepEx (synchapi.h)

Artikel
03/08/2023

Menangguhkan utas saat ini hingga kondisi yang ditentukan terpenuhi. Eksekusi dilanjutkan ketika salah satu hal berikut ini terjadi:

Fungsi panggilan balik penyelesaian I/O dipanggil.
Panggilan prosedur asinkron (APC) diantrekan ke utas.
Interval waktu habis berlalu.

Sintaks

DWORD SleepEx(
  [in] DWORD dwMilliseconds,
  [in] BOOL  bAlertable
);

Parameter

[in] dwMilliseconds

Interval waktu di mana eksekusi akan ditangguhkan, dalam milidetik.

Nilai nol menyebabkan utas melepaskan sisa ikatan waktunya ke utas lain yang siap dijalankan. Jika tidak ada utas lain yang siap dijalankan, fungsi segera kembali, dan utas melanjutkan eksekusi. Windows XP: Nilai nol menyebabkan utas melepaskan sisa ikatan waktunya ke utas lain dengan prioritas yang sama yang siap dijalankan. Jika tidak ada utas lain dengan prioritas yang sama yang siap dijalankan, fungsi segera kembali, dan utas melanjutkan eksekusi. Perilaku ini berubah dimulai dengan Windows Server 2003.

Nilai INFINITE menunjukkan bahwa penangguhan tidak boleh kehabisan waktu.

[in] bAlertable

Jika parameter ini FALSE, fungsi tidak akan kembali hingga periode waktu habis berlalu. Jika panggilan balik penyelesaian I/O terjadi, fungsi tidak segera kembali dan fungsi penyelesaian I/O tidak dijalankan. Jika APC diantrekan ke utas, fungsi tidak segera kembali dan fungsi APC tidak dijalankan.

Jika parameter true dan utas yang memanggil fungsi ini adalah utas yang sama yang disebut fungsi I/O yang diperluas (ReadFileEx atau WriteFileEx), fungsi akan kembali ketika periode waktu habis telah berlalu atau ketika fungsi panggilan balik penyelesaian I/O terjadi. Jika panggilan balik penyelesaian I/O terjadi, fungsi penyelesaian I/O dipanggil. Jika APC diantrekan ke utas (QueueUserAPC), fungsi mengembalikan ketika periode waktu habis telah berlalu atau ketika fungsi APC dipanggil.

Menampilkan nilai

Nilai yang dikembalikan adalah nol jika interval waktu yang ditentukan kedaluwarsa.

Nilai yang dikembalikan WAIT_IO_COMPLETION jika fungsi dikembalikan karena satu atau beberapa fungsi panggilan balik penyelesaian I/O. Ini hanya dapat terjadi jika bAlertable TRUE, dan jika utas yang memanggil fungsi SleepEx adalah utas yang sama yang disebut fungsi I/O yang diperluas.

Keterangan

Fungsi ini menyebabkan utas melepaskan sisa irisan waktunya dan menjadi tidak dapat dijalankan untuk interval berdasarkan nilai dwMilliseconds. Setelah interval tidur berlalu, utas siap dijalankan. Perhatikan bahwa utas siap tidak dijamin akan segera berjalan. Akibatnya, utas tidak akan berjalan sampai beberapa waktu arbitrer setelah interval tidur berlalu, berdasarkan frekuensi "tick" sistem dan faktor beban dari proses lain. Jam sistem "berdetak" pada tingkat konstanta. Untuk meningkatkan akurasi interval tidur, panggil fungsi timeGetDevCaps untuk menentukan resolusi timer minimum yang didukung dan fungsi timeBeginPeriod untuk mengatur resolusi timer ke minimumnya. Berhati-hatilah saat memanggil timeBeginPeriod, karena panggilan yang sering dapat secara signifikan memengaruhi jam sistem, penggunaan daya sistem, dan penjadwal. Jika Anda memanggil timeBeginPeriod, sebut saja satu kali di awal aplikasi dan pastikan untuk memanggil fungsi timeEndPeriod di bagian paling akhir aplikasi. Jika Anda menentukan 0 milidetik, utas akan melepaskan sisa ikatan waktunya tetapi tetap siap. Untuk informasi selengkapnya, lihat Prioritas Penjadwalan.

Fungsi ini dapat digunakan dengan fungsi ReadFileEx atau WriteFileEx untuk menangguhkan utas hingga operasi I/O selesai. Fungsi-fungsi ini menentukan rutinitas penyelesaian yang akan dijalankan ketika operasi I/O telah selesai. Agar rutinitas penyelesaian dijalankan, utas yang memanggil fungsi I/O harus dalam status tunggu yang dapat diperingatkan ketika fungsi panggilan balik penyelesaian terjadi. Utas masuk ke status tunggu yang dapat diperingatkan dengan memanggil SleepEx, MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx, atau WaitForMultipleObjectsEx, dengan parameter bAlertable fungsi diatur ke TRUE.

Berhati-hatilah saat menggunakan SleepEx dalam skenario berikut:

Kode yang secara langsung atau tidak langsung membuat jendela (misalnya, DDE dan COM CoInitialize). Jika utas membuat jendela apa pun, utas harus memproses pesan. Siaran pesan dikirim ke semua jendela dalam sistem. Jika Anda memiliki utas yang menggunakan SleepEx dengan penundaan tak terbatas, sistem akan mengalami kebuntuan.
Utas yang berada di bawah kontrol konkurensi. Misalnya, port penyelesaian I/O atau kumpulan utas membatasi jumlah utas terkait yang dapat berjalan. Jika jumlah maksimum utas sudah berjalan, tidak ada utas terkait tambahan yang dapat berjalan hingga utas yang sedang berjalan selesai. Jika utas menggunakan SleepEx dengan interval nol untuk menunggu salah satu utas terkait tambahan untuk menyelesaikan beberapa pekerjaan, prosesnya mungkin akan mengalami kebuntuan.

Untuk skenario ini, gunakan MsgWaitForMultipleObjects atau MsgWaitForMultipleObjectsEx, bukan SleepEx.

Windows Phone 8.1: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8.1 dan yang lebih baru.

Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Persyaratan


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 (sertakan Windows.h pada Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Pustaka	Kernel32.lib; WindowsPhoneCore.lib di Windows Phone 8.1
DLL	KernelBase.dll di Windows Phone 8.1; Kernel32.dll