Fungsi QueueUserWorkItem (threadpoollegacyapiset.h)

Mengantrekan item kerja ke utas pekerja di kumpulan utas.

Sintaks

BOOL QueueUserWorkItem(
  [in]           LPTHREAD_START_ROUTINE Function,
  [in, optional] PVOID                  Context,
  [in]           ULONG                  Flags
);

Parameter

[in] Function

Penunjuk ke fungsi panggilan balik jenis yang ditentukan aplikasi LPTHREAD_START_ROUTINE untuk dijalankan oleh utas di kumpulan utas. Nilai ini mewakili alamat awal utas. Fungsi panggilan balik ini tidak boleh memanggil fungsi TerminateThread .

Nilai yang dikembalikan dari fungsi panggilan balik tidak digunakan.

Untuk informasi selengkapnya, lihat ThreadProc.

[in, optional] Context

Nilai parameter tunggal yang akan diteruskan ke fungsi utas.

[in] Flags

Bendera yang mengontrol eksekusi. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
WT_EXECUTEDEFAULT 0x00000000	Secara default, fungsi panggilan balik diantrekan ke utas pekerja non-I/O. Fungsi panggilan balik diantrekan ke utas yang menggunakan port penyelesaian I/O, yang berarti mereka tidak dapat melakukan tunggu yang dapat diingat. Oleh karena itu, jika I/O selesai dan menghasilkan APC, APC mungkin menunggu tanpa batas waktu karena tidak ada jaminan bahwa utas akan memasuki status tunggu yang dapat diperingatkan setelah panggilan balik selesai.
WT_EXECUTEINIOTHREAD 0x00000001	Bendera ini tidak digunakan. Windows Server 2003 dan Windows XP: Fungsi panggilan balik diantrekan ke utas pekerja I/O. Bendera ini harus digunakan jika fungsi harus dijalankan dalam utas yang menunggu dalam status yang dapat diperingatkan. Utas pekerja I/O dihapus dimulai dengan Windows Vista dan Windows Server 2008.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	Fungsi panggilan balik diantrekan ke utas yang tidak pernah berakhir. Ini tidak menjamin bahwa utas yang sama digunakan setiap kali. Bendera ini harus digunakan hanya untuk tugas singkat atau dapat memengaruhi operasi timer lainnya. Bendera ini harus diatur jika utas memanggil fungsi yang menggunakan APC. Untuk informasi selengkapnya, lihat Panggilan Prosedur Asinkron. Perhatikan bahwa saat ini tidak ada utas pekerja yang benar-benar persisten, meskipun utas pekerja tidak berakhir jika ada permintaan I/O yang tertunda.
WT_EXECUTELONGFUNCTION 0x00000010	Fungsi panggilan balik dapat melakukan penantian panjang. Bendera ini membantu sistem untuk memutuskan apakah harus membuat utas baru.
WT_TRANSFER_IMPERSONATION 0x00000100	Fungsi panggilan balik akan menggunakan token akses saat ini, baik itu token proses atau peniruan. Jika bendera ini tidak ditentukan, fungsi panggilan balik hanya dijalankan dengan token proses. Windows XP: Bendera ini tidak didukung sampai Windows XP SP2 dan Windows Server 2003.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Jika fungsi dalam DLL diantrekan ke utas pekerja, pastikan bahwa fungsi telah menyelesaikan eksekusi sebelum DLL dibongkar.

Secara default, kumpulan utas memiliki maksimum 512 utas per proses. Untuk menaikkan batas antrean, gunakan makro WT_SET_MAX_THREADPOOL_THREAD yang ditentukan di WinNT.h.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

Gunakan makro ini dalam panggilan ke QueueUserWorkItem untuk menentukan parameter Bendera . Parameter makro adalah bendera yang diinginkan dan batas baru, hingga (2<<16)-1 utas. Namun, ukuran antrean dibatasi oleh ukuran kumpulan kernel yang tidak bertumpuk. Perhatikan bahwa aplikasi Anda dapat meningkatkan performanya dengan menjaga jumlah utas pekerja tetap rendah.

Untuk mengkompilasi aplikasi yang menggunakan fungsi ini, tentukan _WIN32_WINNT sebagai 0x0500 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menggunakan Header Windows.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	threadpoollegacyapiset.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

Lihat juga

Fungsi Proses dan Utas

Pengumpulan Utas

ThreadProc