Share via

QueueUserWorkItem 函式 (threadpoollegacyapiset.h)

  • 發行項

將工作專案排入 線程集區中的背景工作線程。

語法

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

參數

[in] Function

線程集區中線程所要執行 之類型LPTHREAD_START_ROUTINE 應用程式定義回呼函式的指標。 這個值代表線程的起始位址。 這個回呼函式不得呼叫 TerminateThread 函式。

不會使用回呼函式的傳回值。

如需詳細資訊，請參閱 ThreadProc。

[in, optional] Context

要傳遞至線程函式的單一參數值。

[in] Flags

控制執行的旗標。 此參數可以是下列一或多個值。

值 意義
WT_EXECUTEDEFAULT
0x00000000
 根據預設，回呼函式會排入佇列至非 I/O 背景工作線程。

回呼函式會排入使用 I/O 完成埠的線程，這表示它們無法執行可警示的等候。 因此，如果 I/O 完成併產生 APC，APC 可能會無限期等候，因為線程在回呼完成之後將進入可警示的等候狀態。
WT_EXECUTEINIOTHREAD
0x00000001
 未使用這個旗標。

Windows Server 2003 和 Windows XP： 回呼函式會排入佇列至 I/O 背景工作線程。 如果函式應在等候處於可警示狀態的線程中執行，則應該使用此旗標。

從 Windows Vista 和 Windows Server 2008 開始，已移除 I/O 背景工作線程。
WT_EXECUTEINPERSISTENTTHREAD
0x00000080
 回呼函式會排入永遠不會終止的線程。 它不保證每次都使用相同的線程。 此旗標只應用於簡短工作，或可能會影響其他定時器作業。

如果線程呼叫使用 APC 的函式，就必須設定此旗標。 如需詳細資訊，請參閱 異步過程調用。

請注意，目前沒有任何背景工作線程確實是持續性的，雖然背景工作線程不會在有任何擱置的 I/O 要求時終止。
WT_EXECUTELONGFUNCTION
0x00000010
 回呼函式可以執行長時間等候。 此旗標可協助系統決定是否應該建立新的線程。
WT_TRANSFER_IMPERSONATION
0x00000100
 回呼函式會使用目前的存取令牌，無論是進程或模擬令牌。 如果未指定此旗標，回呼函式只會以進程令牌執行。

Windowsxp： 在 Windows XP SP2 和 Windows Server 2003 之前，不支援此旗標。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

如果 DLL 中的函式排入背景工作線程，請確定函式已在卸除 DLL 之前完成執行。

根據預設，線程集區每個進程最多有512個線程。 若要提高佇列限制，請使用 WinNT.h 中定義的 WT_SET_MAX_THREADPOOL_THREAD 宏。

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

在 對 QueueUserWorkItem 的呼叫中使用這個宏來指定 Flags 參數。 宏參數是所需的旗標和新的限制，最多 (2<<個 16 個) -1 個線程。 不過，佇列的大小受限於核心非分頁集區的大小。 請注意，您的應用程式可以藉由讓背景工作線程數目保持低來改善其效能。

若要編譯使用此函式的應用程式，請將 _WIN32_WINNT 定義為0x0500或更新版本。 如需詳細資訊，請參閱 使用 Windows 標頭。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 threadpoollegacyapiset.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

處理序和執行緒函式

執行緒共用

ThreadProc