Share via

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 為零，函式會測試物件的狀態並立即傳回。 如果 dwMilliseconds 是 INFINITE，則函式的超時時間間隔永遠不會經過。

[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
 回呼函式是由等候線程本身叫用。 此旗標只應用於簡短工作，或可能會影響其他等候作業。

如果某些其他線程取得獨佔鎖定，並在回呼函式嘗試取得相同的鎖定時呼叫 UnregisterWait 或 UnregisterWaitEx 函 式，就會發生死結。
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 函式。 相反地，使用 SetThreadpoolThreadpoolThreadMaximum 和 SetThreadpoolThreadMinimum 函式來設定線程集區上限，或使用 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