Fungsi CloseThreadpoolCleanupGroupMembers (threadpoolapiset.h)

Artikel
03/08/2023

Merilis anggota grup pembersihan yang ditentukan, menunggu semua fungsi panggilan balik selesai, dan secara opsional membatalkan fungsi panggilan balik yang luar biasa.

Sintaks

void CloseThreadpoolCleanupGroupMembers(
  [in, out]           PTP_CLEANUP_GROUP ptpcg,
  [in]                BOOL              fCancelPendingCallbacks,
  [in, out, optional] PVOID             pvCleanupContext
);

Parameter

[in, out] ptpcg

Penunjuk ke struktur TP_CLEANUP_GROUP yang menentukan grup pembersihan. Fungsi CreateThreadpoolCleanupGroup mengembalikan penunjuk ini.

[in] fCancelPendingCallbacks

Jika parameter ini TRUE, fungsi membatalkan panggilan balik luar biasa yang belum dimulai. Jika parameter ini FALSE, fungsi menunggu fungsi panggilan balik yang luar biasa selesai.

[in, out, optional] pvCleanupContext

Data yang ditentukan aplikasi untuk diteruskan ke fungsi panggilan balik grup pembersihan aplikasi. Anda dapat menentukan fungsi panggilan balik saat memanggil SetThreadpoolCallbackCleanupGroup.

Mengembalikan nilai

Tidak ada

Keterangan

Fungsi CloseThreadpoolCleanupGroupMembers menyederhanakan pembersihan objek panggilan balik kumpulan utas dengan merilis, dalam satu operasi, semua objek kerja, objek tunggu, dan objek timer yang merupakan anggota grup pembersihan. Objek menjadi anggota grup pembersihan saat objek dibuat dengan lingkungan panggilan balik threadpool yang ditentukan saat grup pembersihan dibuat. Untuk informasi selengkapnya, lihat CreateThreadpoolCleanupGroup.

Fungsi CloseThreadpoolCleanupGroupMembers memblokir hingga semua fungsi panggilan balik yang sedang dijalankan selesai. Jika fCancelPendingCallbacks TRUE, panggilan balik yang terutang dibatalkan; jika tidak, fungsi memblokir sampai semua panggilan balik yang luar biasa juga selesai. Setelah fungsi CloseThreadpoolCleanupGroupMembers kembali, aplikasi tidak boleh menggunakan objek apa pun yang merupakan anggota grup pembersihan pada saat CloseThreadpoolCleanupGroupMembers dipanggil. Selain itu, aplikasi tidak boleh merilis objek apa pun satu per satu dengan memanggil fungsi seperti CloseThreadpoolWork, karena objek telah dirilis.

Fungsi CloseThreadpoolCleanupGroupMembers tidak menutup grup pembersihan itu sendiri. Sebaliknya, grup pembersihan tetap ada sampai fungsi CloseThreadpoolCleanupGroup dipanggil. Selain itu, menutup grup pembersihan tidak memengaruhi lingkungan panggilan balik threadpool terkait. Lingkungan panggilan balik bertahan sampai dihancurkan dengan memanggil DestroyThreadpoolEnvironment.

Selama grup pembersihan berlanjut, objek baru yang dibuat dengan lingkungan panggilan balik threadpool terkait grup pembersihan ditambahkan ke grup pembersihan. Ini memungkinkan aplikasi untuk menggunakan kembali grup pembersihan. Namun, ini dapat menyebabkan kesalahan jika aplikasi tidak menyinkronkan kode yang memanggil CloseThreadpoolCleanupGroupMembers dengan kode yang membuat objek baru. Misalnya, utas membuat dua objek kerja threadpool, Work1 dan Work2. Utas lain memanggil CloseThreadpoolCleanupGroupMembers. Bergantung pada kapan utas berjalan, salah satu hal berikut mungkin terjadi:

Work1 dan Work2 ditambahkan ke grup pembersihan setelah anggota yang ada dirilis. Kode yang mengirimkan Work1 dan Work2 akan berhasil.
Work1 ditambahkan ke grup pembersihan sebelum anggotanya yang ada dirilis, menyebabkan Work1 dirilis bersama dengan anggota lain. Kemudian Work2 ditambahkan. Kode yang mengirimkan Work1 akan menghasilkan pengecualian; kode yang mengirimkan Work2 akan berhasil.
Work1 dan Work2 ditambahkan ke grup pembersihan sebelum anggota yang ada dirilis, menyebabkan Work1 dan Work2 dirilis. Kode yang mengirimkan Work1 atau Work2 akan menghasilkan pengecualian.

Untuk hanya menunggu atau membatalkan item kerja yang tertunda tanpa merilisnya, gunakan salah satu fungsi panggilan balik threadpool: WaitForThreadpoolIoCallbacks, WaitForThreadpoolTimerCallbacks, WaitForThreadpoolWaitCallbacks, atau WaitForThreadpoolWorkCallbacks.

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 Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	threadpoolapiset.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll