Fungsi SetThreadpoolTimerEx (threadpoolapiset.h)

Artikel
03/08/2023

Mengatur objek timer, mengganti timer sebelumnya, jika ada. Utas pekerja memanggil panggilan balik objek timer setelah batas waktu yang ditentukan kedaluwarsa.

Sintaks

BOOL SetThreadpoolTimerEx(
  [in, out]      PTP_TIMER pti,
  [in, optional] PFILETIME pftDueTime,
  [in]           DWORD     msPeriod,
  [in, optional] DWORD     msWindowLength
);

Parameter

[in, out] pti

Penunjuk ke struktur TP_TIMER yang menentukan objek timer yang akan diatur. Fungsi CreateThreadpoolTimer mengembalikan penunjuk ini.

[in, optional] pftDueTime

Penunjuk ke struktur FILETIME yang menentukan waktu absolut atau relatif di mana timer harus kedaluwarsa. Jika parameter ini menunjuk ke nilai positif, parameter menunjukkan waktu absolut sejak 1 Januari 1601 (UTC), diukur dalam 100 unit nanodetik. Jika parameter ini menunjuk ke nilai negatif, parameter menunjukkan jumlah waktu untuk menunggu relatif terhadap waktu saat ini. Jika parameter ini menunjuk ke nol, maka timer akan segera kedaluwarsa. Untuk informasi selengkapnya tentang nilai waktu, lihat Waktu File.

Jika parameter ini NULL, objek timer akan berhenti mengantre panggilan balik baru (tetapi panggilan balik yang sudah diantrekan akan tetap terjadi).

Timer diatur jika parameter pftDueTime non-NULL.

[in] msPeriod

Periode timer, dalam milidetik. Jika parameter ini nol, timer disinyalir sekali. Jika parameter ini lebih besar dari nol, timer berkala. Timer berkala secara otomatis diaktifkan kembali setiap kali periode berlalu, hingga timer dibatalkan.

[in, optional] msWindowLength

Jumlah maksimum waktu yang dapat ditunda sistem sebelum memanggil panggilan balik timer. Jika parameter ini diatur, sistem dapat melakukan batch panggilan untuk menghemat daya.

Nilai kembali

Mengembalikan TRUE jika timer sebelumnya diatur dan dibatalkan. Jika tidak, mengembalikan FALSE.

Jika status timer sebelumnya adalah "set", dan fungsi mengembalikan FALSE, maka panggilan balik sedang berlangsung atau akan dimulai. Lihat komentar untuk diskusi lebih lanjut.

Keterangan

Mengatur timer akan membatalkan timer sebelumnya, jika ada.

Dalam beberapa kasus, fungsi panggilan balik mungkin berjalan setelah aplikasi menutup timer threadpool. Untuk mencegah perilaku ini, aplikasi harus mengikuti langkah-langkah yang dijelaskan di CloseThreadpoolTimer.

Jika waktu jatuh tempo yang ditentukan oleh pftDueTime relatif, waktu yang dihabiskan sistem dalam tidur atau hibernasi tidak dihitung terhadap kedaluwarsa timer. Timer disinyalir ketika jumlah kumulatif waktu yang berlalu yang dihabiskan sistem dalam keadaan bangun sama dengan waktu atau periode jatuh tempo relatif timer. Jika waktu jatuh tempo yang ditentukan oleh pftDueTime adalah absolut, waktu yang dihabiskan sistem dalam tidur atau hibernasi dihitung terhadap kedaluwarsa timer. Jika timer kedaluwarsa saat sistem tidur, timer akan segera disinyalir ketika sistem bangun.

Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0600 atau lebih tinggi.

Contoh

Misalnya, lihat Menggunakan Fungsi Kumpulan Utas.

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	threadpoolapiset.h
Pustaka	Kernel32.lib
DLL	Kernel32.dll