SleepEx 函式 (synchapi.h)

發行項
08/26/2023

暫停目前的執行緒，直到符合指定的條件為止。發生下列其中一項時，執行會繼續：

呼叫 I/O 完成回呼函式。
非同步程序呼叫 (APC) 已排入執行緒。
逾時間隔經過。

語法

DWORD SleepEx(
  [in] DWORD dwMilliseconds,
  [in] BOOL  bAlertable
);

參數

[in] dwMilliseconds

要暫停執行的時間間隔，以毫秒為單位。

值為零會導致執行緒將其時間配量其餘部分放棄為任何其他準備好執行的執行緒。如果沒有其他執行緒可供執行，函式會立即傳回，而執行緒會繼續執行。Windowsxp： 值為零會導致執行緒將其時間配量其餘部分放棄為任何其他已準備好執行之優先順序相同的執行緒。如果沒有其他優先順序相等的執行緒可供執行，函式會立即傳回，而執行緒會繼續執行。此行為從 Windows Server 2003 開始變更。

INFINITE 的值表示暫停不應該逾時。

[in] bAlertable

如果此參數為 FALSE，則函式不會在逾時期間經過之前傳回。如果發生 I/O 完成回呼，函式不會立即傳回，而且不會執行 I/O 完成函式。如果 APC 已排入執行緒佇列，則函式不會立即傳回，而且不會執行 APC 函式。

如果參數為 TRUE，且呼叫此函式的執行緒與呼叫擴充 I/O 函式的執行緒相同， (ReadFileEx 或 WriteFileEx) ，則函式會在逾時期間經過或發生 I/O 完成回呼函式時傳回。如果發生 I/O 完成回呼，則會呼叫 I/O 完成函式。如果 APC 排入執行緒 (QueueUserAPC) ，則當逾時期間經過或呼叫 APC 函式時，函式會傳回。

傳回值

如果指定的時間間隔過期，則傳回值為零。

如果函式因為一或多個 I/O 完成回呼函式而傳回，則傳回值 WAIT_IO_COMPLETION 。只有當 bAlertable 為 TRUE，而且呼叫 SleepEx 函式的執行緒與呼叫擴充 I/O 函式的執行緒相同時，才會發生此情況。

備註

此函式會讓執行緒放棄其時間配量的其餘部分，並根據 dwMilliseconds的值，在間隔中變成無法執行。進入睡眠間隔之後，執行緒便準備好執行。請注意，就緒執行緒不保證會立即執行。因此，在睡眠間隔經過一些任意時間之後，執行緒才會執行，根據系統「刻度」頻率和其他進程的負載因數。系統時鐘會以固定速率「刻度」。若要增加睡眠間隔的精確度，請呼叫 timeGetDevCaps 函式來判斷支援的最小計時器解析度，以及 timeBeginPeriod 函式，將計時器解析度設定為最小值。呼叫 timeBeginPeriod時請小心，因為頻繁的呼叫可能會大幅影響系統時鐘、系統電源使用量和排程器。如果您呼叫 timeBeginPeriod，請在應用程式中提早呼叫它一次，並確定在應用程式的結尾呼叫 timeEndPeriod 函式。如果您指定 0 毫秒，執行緒將會放棄其時間配量的其餘部分，但仍保持就緒。如需詳細資訊，請參閱排程優先順序。

此函式可以搭配 ReadFileEx 或 WriteFileEx 函式使用，以暫停執行緒，直到 I/O 作業完成為止。這些函式會指定要在 I/O 作業完成時執行的完成常式。若要執行完成常式，呼叫 I/O 函式的執行緒必須在完成回呼函式發生時處於可警示的等候狀態。執行緒會呼叫 SleepEx、 MsgWaitForMultipleObjectsEx、 WaitForSingleObjectEx或 WaitForMultipleObjectsEx，將函式的 bAlertable 參數設定為 TRUE，進入可警示的等候狀態。

在下列案例中使用 SleepEx 時請小心：

直接或間接建立視窗的程式碼 (例如 DDE 和 COM CoInitialize) 。如果執行緒建立任何視窗，則必須處理訊息。訊息廣播會傳送至系統中的所有視窗。如果您有使用 SleepEx 的執行緒具有無限延遲，系統將會死結。
並行控制下的執行緒。例如，I/O 完成埠或執行緒集區會限制可執行檔相關聯執行緒數目。如果執行緒數目上限已在執行中，則在執行中的執行緒完成之前，不會執行其他相關聯的執行緒。如果執行緒使用 SleepEx 的間隔為零，等候其中一個額外的相關聯執行緒完成某些工作，進程可能會死結。

在這些案例中，請使用 MsgWaitForMultipleObjects 或 MsgWaitForMultipleObjectsEx，而不是 SleepEx。

Windows Phone 8.1：Windows Phone 8.1 和更新版本上的 Windows Phone Store 應用程式支援此函式。

Windows 8.1和Windows Server 2012 R2：Windows 市集應用程式支援此功能，Windows 8.1、Windows Server 2012 R2 及更新版本。

需求


最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	synchapi.h (包含 Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)
程式庫	Kernel32.lib;Windows Phone 8.1 上的 WindowsPhoneCore.lib
Dll	Windows Phone 8.1 上的 KernelBase.dll;Kernel32.dll