共用方式為


RegisterWaitForSingleObject 函式 (winbase.h)

指示 線程集 區中的等候線程等候物件。 等候線程會在發生下列其中一項時,將指定的回調函式排入線程集區:

  • 指定的物件處於訊號狀態。
  • 逾時間隔經過。

語法

BOOL RegisterWaitForSingleObject(
  [out]          PHANDLE             phNewWaitObject,
  [in]           HANDLE              hObject,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Context,
  [in]           ULONG               dwMilliseconds,
  [in]           ULONG               dwFlags
);

參數

[out] phNewWaitObject

在傳回時接收等候句柄之變數的指標。 請注意,等候句柄不能用於需要物件句柄的函式中,例如 CloseHandle

[in] hObject

物件的句柄。 如需可以指定句柄的物件類型清單,請參閱下列一節。

如果等候仍在擱置時關閉此句柄,則函式的行為是未定義的。

句柄必須具有 SYNCHRONIZE 訪問許可權。 如需詳細資訊,請參閱 標準訪問許可權

[in] Callback

hObject 處於訊號狀態或 dwMilliseconds 耗用時,要執行之 WAITORTIMERCALLBACK 類型的應用程式定義函式指標。 如需詳細資訊,請參閱 WaitOrTimerCallback

[in, optional] Context

傳遞至回調函式的單一值。

[in] dwMilliseconds

超時時間間隔,以毫秒為單位。 如果間隔經過,則函式會傳回 ,即使物件的狀態為非ignaled 也一樣。 如果 dwMilliseconds 為零,函式會測試物件的狀態並立即傳回。 如果 dwMillisecondsINFINITE,則函式的超時時間間隔永遠不會經過。

[in] dwFlags

此參數可以是下列一或多個值。

如需將這些值與維持訊號的物件搭配使用的相關信息,請參閱一節。

意義
WT_EXECUTEDEFAULT
0x00000000
根據預設,回呼函式會排入佇列至非 I/O 背景工作線程。
WT_EXECUTEINIOTHREAD
0x00000001
未使用這個旗標。

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

從 Windows Vista 和 Windows Server 2008 開始,已移除 I/O 背景工作線程。

WT_EXECUTEINPERSISTENTTHREAD
0x00000080
回呼函式會排入永遠不會終止的線程。 它不保證每次都使用相同的線程。 此旗標只應用於簡短工作,或可能會影響其他等候作業。

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

請注意,目前沒有任何背景工作線程真正持續存在,不過沒有任何背景工作線程會在有任何擱置的 I/O 要求時終止。

WT_EXECUTEINWAITTHREAD
0x00000004
回呼函式是由等候線程本身叫用。 此旗標只應用於簡短工作,或可能會影響其他等候作業。

如果某些其他線程取得獨佔鎖定,並在回呼函式嘗試取得相同的鎖定時呼叫 UnregisterWaitUnregisterWaitEx 函 式,就會發生死結。

WT_EXECUTELONGFUNCTION
0x00000010
回呼函式可以執行長時間等候。 此旗標可協助系統決定是否應該建立新的線程。
WT_EXECUTEONLYONCE
0x00000008
呼叫回呼函式之後,線程將不再等候句柄。 否則,每次等候作業完成時都會重設定時器,直到取消等候作業為止。
WT_TRANSFER_IMPERSONATION
0x00000100
回呼函式會使用目前的存取令牌,無論是進程或模擬令牌。 如果未指定此旗標,回呼函式只會以進程令牌執行。

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

傳回值

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

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

備註

新的等候線程會在需要時自動建立。 等候作業是由線程集區的等候線程執行。 當物件的狀態變成訊號或逾時間隔經過時,背景工作線程會執行回呼例程。 如果 dwFlags 不是 WT_EXECUTEONLYONCE,則每次發出訊號或逾時間隔經過時,都會重設定時器。

等候完成時,您必須呼叫 UnregisterWait 或 UnregisterWaitEx 函式來取消等候作業。 (即使是使用 WT_EXECUTEONLYONCE 的等候作業也必須取消。) 請勿從回呼函式內對其中一個函式進行封鎖呼叫。

請注意,您不應該對傳遞至 RegisterWaitForSingleObject 的事件對象發出脈衝,因為等候線程可能不會偵測到事件在重設之前收到訊號。 除非您設定 WT_EXECUTEONLYONCE 或WT_EXECUTEINWAITTHREAD旗標,否則您不應該註冊仍 (收到訊號的物件,例如手動重設事件或終止的進程 ) 。 針對其他旗標,在重設事件之前,回呼函式可能會呼叫太多次。

函式會修改某些同步處理物件類型的狀態。 修改只會針對發出訊號狀態導致滿足等候條件的對象發生。 例如,號誌物件的計數會減少一。

RegisterWaitForSingleObject 函式可以等候下列物件:

  • 變更通知
  • 主控台輸入
  • 事件
  • 記憶體資源通知
  • Mutex
  • 流程
  • Semaphore
  • 執行緒
  • 可等候定時器
如需詳細資訊,請參閱 同步處理物件

根據預設,線程集區最多有500個線程。 若要提高此限制,請使用 WinNT.h 中定義的 WT_SET_MAX_THREADPOOL_THREAD 宏。

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

指定 dwFlags 參數時,請使用這個宏。 宏參數是所需的旗標,而新的限制 (最多 (2<<16 個) -1 個線程) 。 不過,請注意,您的應用程式可以藉由讓背景工作線程數目保持低,以改善其效能。

工作專案及其呼叫的所有函式都必須是安全線程集區。 因此,您無法從預設回呼環境呼叫需要持續線程的異步呼叫,例如 RegNotifyChangeKeyValue 函式。 相反地,使用 SetThreadpoolThreadpoolThreadMaximumSetThreadpoolThreadMinimum 函式來設定線程集區上限,或使用 CreateThread 函式建立您自己的線程。 (針對原始線程集區 API,請使用 QueueUserWorkItem 函式指定WT_EXECUTEINPERSISTENTTHREAD。)

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

規格需求

需求
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 winbase.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

同步處理函式

執行緒共用

UnregisterWait

UnregisterWaitEx

Wait 函式

WaitOrTimerCallback