SignalObjectAndWait 函式 (synchapi.h)

  • 發行項

發出一個對象的訊號，並等候另一個物件做為單一作業。

語法

DWORD SignalObjectAndWait(
  [in] HANDLE hObjectToSignal,
  [in] HANDLE hObjectToWaitOn,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

參數

[in] hObjectToSignal

要發出訊號之物件的句柄。 這個物件可以是號誌、mutex 或事件。

如果句柄是號誌，則需要 SEMAPHORE_MODIFY_STATE 訪問許可權。 如果句柄是事件，則需要 EVENT_MODIFY_STATE 訪問許可權。 如果句柄是 mutex，而且呼叫端沒有 mutex，則函式會失敗並 ERROR_NOT_OWNER。

[in] hObjectToWaitOn

要等候之物件的句柄。 需要 SYNCHRONIZE 訪問許可權;如需詳細資訊，請參閱 同步處理物件安全性和訪問許可權。 如需您可以指定句柄的物件類型清單，請參閱一節。

[in] dwMilliseconds

超時時間間隔，以毫秒為單位。 如果間隔經過，則函式會傳回 ，即使物件的狀態為非簽署狀態，也不會將完成或異步過程調用排入佇列 (APC) 物件。 如果 dwMilliseconds 為零，函式會測試物件的狀態、檢查佇列完成例程或 APC，然後立即傳回。 如果 dwMilliseconds 是 INFINITE，則函式的超時時間間隔永遠不會經過。

[in] bAlertable

如果此參數為 TRUE，當系統將 I/O 完成例程或 APC 函式排入佇列時，函式會傳回 ，而線程會呼叫函式。 如果為 FALSE，則函式不會傳回，而且線程不會呼叫完成例程或 APC 函式。

完成例程會在將 APC 排入佇列的函式呼叫完成時排入佇列。 只有當 bAlertable 為 TRUE，且呼叫線程是排入 APC 的線程時，此函式才會傳回並呼叫完成例程。

傳回值

如果函式成功，傳回值會指出導致函式傳回的事件。 它可以是下列值之一。

傳回碼/值 Description
WAIT_ABANDONED
0x00000080L
 指定的物件是 Mutex 物件，不是由擁有 Mutex 物件的線程在擁有線程終止之前釋放的 Mutex 物件。 mutex 對象的擁有權會授與呼叫線程，且 mutex 設定為非ignaled。

如果 Mutex 正在保護持續性狀態資訊，您應該檢查該資訊是否一致性。
WAIT_IO_COMPLETION
0x000000C0L
 等候已由一或多個使用者模式 異步過程調用 結束， (APC) 佇列至線程。
WAIT_OBJECT_0
0x00000000L
 指定物件的狀態會發出訊號。
WAIT_TIMEOUT
0x00000102L
 經過逾時間隔，且物件的狀態為非ignaled。
WAIT_FAILED
(DWORD) 0xFFFFFFFF
 函式失敗。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

SignalObjectAndWait 函式提供更有效率的方式，可對某個對象發出訊號，然後等候另一個物件，相較於個別的函數調用，例如 SetEvent，後面接著 WaitForSingleObject。

SignalObjectAndWait 函式可以等候下列物件：

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

線程可以使用 SignalObjectAndWait 函式來確保背景工作線程在發出物件訊號之前處於等候狀態。 例如，線程和背景工作線程可能會使用句柄來同步處理其工作。 線程會執行下列程式代碼：

  dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
  if( WAIT_OBJECT_0 == dwRet)
    SetEvent(hEventMoreWorkToDo);

背景工作線程會執行下列程式代碼：

  dwRet = SignalObjectAndWait(hEventWorkerDone,
                              hEventMoreWorkToDo,
                              INFINITE, 
                              FALSE);

請注意，「訊號」和「等候」不保證會以不可部分完成的作業執行。 在其他處理器上執行的線程可以在呼叫 SignalObjectAndWait 的線程開始第二個物件的等候之前，觀察第一個對象的訊號狀態。

搭配 Windows 7 使用 SignalObjectAndWait 和PulseEvent 時，請特別小心，因為在這些線程之間使用這些 API 可能會導致應用程式死結。 SignalObjectAndWait 發出訊號的線程會呼叫 PulseEvent，以向 SignalObjectAndWait 呼叫的等候對象發出訊號。 在某些情況下， SignalObjectAndWait 的呼叫端無法及時收到等候物件的訊號狀態，導致死結。

使用直接或間接建立視窗的等候函式和程式代碼時，請小心。 如果線程建立任何視窗，它就必須處理訊息。 訊息廣播會傳送至系統中的所有視窗。 使用沒有超時時間間隔之等候函式的線程可能會導致系統死結。 間接建立視窗的程式代碼範例包括 DDE 和 COM CoInitialize。 因此，如果您有建立窗口的線程，請務必從不同的線程呼叫 SignalObjectAndWait 。 如果無法這樣做，您可以使用 MsgWaitForMultipleObjects 或 MsgWaitForMultipleObjectsEx，但功能不相等。

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

規格需求

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

另請參閱

MsgWaitForMultipleObjects

MsgWaitForMultipleObjectsEx

同步處理函式

Wait 函式