Fungsi QueueUserAPC (processthreadsapi.h)

Artikel
03/01/2024

Menambahkan objek panggilan prosedur asinkron (APC) mode pengguna ke antrean APC dari utas yang ditentukan.

Sintaks

DWORD QueueUserAPC(
  [in] PAPCFUNC  pfnAPC,
  [in] HANDLE    hThread,
  [in] ULONG_PTR dwData
);

Parameter

[in] pfnAPC

Penunjuk ke fungsi APC yang disediakan aplikasi untuk dipanggil ketika utas yang ditentukan melakukan operasi tunggu yang dapat diperingatkan. Untuk informasi selengkapnya, lihat fungsi panggilan balik PAPCFUNC.

[in] hThread

Handel ke utas. Handel harus memiliki hak akses THREAD_SET_CONTEXT . Untuk informasi selengkapnya, lihat Keamanan Objek Sinkronisasi dan Hak Akses.

[in] dwData

Nilai tunggal yang diteruskan ke fungsi APC yang ditunjukkan oleh parameter pfnAPC .

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError. Windows Server 2003 dan Windows XP: Tidak ada nilai kesalahan yang ditentukan untuk fungsi ini yang dapat diambil dengan memanggil GetLastError.

Keterangan

Lihat fungsi QueueUserAPC2 untuk informasi tentang APC mode pengguna khusus.

Dukungan APC yang disediakan dalam sistem operasi memungkinkan aplikasi untuk mengantre objek APC ke utas. Untuk memastikan keberhasilan eksekusi fungsi yang digunakan oleh APC, APC harus diantrekan hanya ke utas dalam proses pemanggil.

Catatan

MengantreKAN APC ke utas di luar proses pemanggil tidak disarankan karena sejumlah alasan. Rebasing DLL dapat menyebabkan alamat fungsi yang digunakan oleh APC salah ketika fungsi dijalankan di luar proses pemanggil. Demikian pula, jika proses 64-bit mengantre APC ke proses 32-bit atau sebaliknya, alamat akan salah dan aplikasi akan crash. Faktor lain dapat mencegah keberhasilan eksekusi fungsi, bahkan jika alamat diketahui.

Setiap utas memiliki antrean APC sendiri. Antrean APC adalah permintaan untuk utas untuk memanggil fungsi APC. Sistem operasi mengeluarkan gangguan perangkat lunak untuk mengarahkan utas untuk memanggil fungsi APC.

Ketika APC mode pengguna diantrekan, utas tidak diarahkan untuk memanggil fungsi APC kecuali dalam status yang dapat diperingatkan. Setelah utas dalam status dapat diperingatkan, utas menangani semua APC yang tertunda dalam urutan pertama masuk, keluar pertama (FIFO), dan operasi tunggu kembali WAIT_IO_COMPLETION. Utas memasuki status yang dapat diperingatkan dengan menggunakan fungsi SleepEx, fungsi SignalObjectAndWait, fungsi WaitForSingleObjectEx, fungsi WaitForMultipleObjectsEx, atau fungsi MsgWaitForMultipleObjectsEx.

Jika aplikasi mengantre APC sebelum utas mulai berjalan, utas dimulai dengan memanggil fungsi APC. Setelah utas memanggil fungsi APC, alur memanggil fungsi APC untuk semua APC dalam antrean APC-nya.

Dimungkinkan untuk tidur atau menunggu objek dalam APC. Jika Anda melakukan tunggu yang dapat diperingatkan di dalam APC, APC akan dikirim secara rekursif. Ini dapat menyebabkan luapan tumpukan.

Ketika utas dihentikan menggunakan fungsi ExitThread atau fungsi TerminateThread , APC dalam antrean APC-nya hilang. Fungsi APC tidak dipanggil.

Ketika utas sedang dalam proses dihentikan, memanggil QueueUserAPC untuk ditambahkan ke antrean APC utas akan gagal dengan (31) ERROR_GEN_FAILURE.

Perhatikan bahwa fungsi ReadFileEx, fungsi SetWaitableTimer, dan fungsi WriteFileEx diimplementasikan menggunakan APC sebagai mekanisme panggilan balik pemberitahuan penyelesaian.

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	processthreadsapi.h (termasuk Windows.h pada Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Bagikan melalui