Share via

UnregisterWaitEx 函式 (threadpoollegacyapiset.h)

  • 發行項

取消 RegisterWaitForSingleObject 函式所發出的已註冊等候作業。

語法

BOOL UnregisterWaitEx(
  [in]           HANDLE WaitHandle,
  [in, optional] HANDLE CompletionEvent
);

參數

[in] WaitHandle

等候句柄。 RegisterWaitForSingleObject 函式會傳回此句柄。

[in, optional] CompletionEvent

等候作業取消註冊時要發出訊號的事件物件句柄。 此參數可以是 Null。

如果此參數 INVALID_HANDLE_VALUE，函式會等候所有回呼函式完成再傳回。

如果此參數為 NULL，函式會將定時器標示為刪除，並立即傳回。 不過，大部分的呼叫端都應該等候回呼函式完成，以便執行任何必要的清除。

如果呼叫端提供此事件，且函式成功，或函式失敗且 ERROR_IO_PENDING，則除非收到訊號，否則請勿關閉事件。

傳回值

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

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

備註

您無法在相同等候作業的回調函式內對 UnregisterWaitEx 進行封鎖呼叫。 否則，回呼會等候本身完成。 一般而言， 對 UnregisterWaitEx 的封鎖呼叫會在目前的線程與回呼之間建立相依性，因此若要在另一個等候作業上封鎖取消註冊呼叫，您必須確定回呼函式不會相依於彼此，而第二個等候作業也不會在第一個作業上執行封鎖取消註冊呼叫。

在持續性線程上發出封鎖 UnregisterWaitEx 呼叫時，請小心。 如果使用 WT_EXECUTEINPERSISTENTTHREAD 建立正在取消註冊的等候作業，可能會發生死結。

對 UnregisterWaitEx 進行非封鎖呼叫之後，就無法將與 WaitHandle 相關聯的新回呼函式排入佇列。 不過，可能有擱置的回呼函式已排入佇列給背景工作線程。

在某些情況下，如果 CompletionEvent 為 NULL，函式將會失敗，並ERROR_IO_PENDING。 這表示有未完成的回呼函式。 這些回呼將會執行，或是在執行中。

如果 CompletionEvent 是呼叫端所提供事件的句柄，則函式可能會成功、失敗並出現 ERROR_IO_PENDING，或因不同的錯誤碼而失敗。 如果函式成功，或函式失敗並 ERROR_IO_PENDING，則呼叫端應該一律等到事件收到訊號以關閉事件為止。 如果函式因不同的錯誤碼而失敗，就不需要等到事件收到訊號以關閉事件為止。

Windowsxp： 如果 CompletionEvent 是呼叫端所提供的事件句柄，且函式失敗並 ERROR_IO_PENDING，則呼叫端應該等到事件收到訊號以關閉事件為止。 此行為從 Windows Vista 開始變更。

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

規格需求

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

另請參閱

RegisterWaitForSingleObject

同步處理函式

執行緒共用