Функция SleepEx (synchapi.h)

Статья
03/08/2023

Приостанавливает текущий поток до тех пор, пока не будет выполнено указанное условие. Выполнение возобновляется при выполнении одного из следующих действий:

Вызывается функция обратного вызова завершения ввода-вывода.
Асинхронный вызов процедуры (APC) помещается в очередь в поток.
Истекает интервал времени ожидания.

Синтаксис

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

Параметры

[in] dwMilliseconds

Интервал времени, на который приостанавливается выполнение, в миллисекундах.

Нулевое значение приводит к тому, что поток откажется от оставшейся части своего среза времени любому другому потоку, готовому к выполнению. Если нет других потоков, готовых к выполнению, функция возвращается немедленно, и поток продолжит выполнение. Windows XP: Нулевое значение приводит к тому, что поток откажется от оставшейся части своего среза времени любому другому потоку с равным приоритетом, который готов к выполнению. Если нет других потоков с равным приоритетом, готовых к выполнению, функция возвращается немедленно, и поток продолжит выполнение. Это поведение изменилось начиная с Windows Server 2003.

Значение INFINITE указывает, что время ожидания приостановки не должно истекать.

[in] bAlertable

Если этот параметр имеет значение FALSE, функция не возвращается до истечения времени ожидания. Если выполняется обратный вызов завершения ввода-вывода, функция не возвращается немедленно и функция завершения ввода-вывода не выполняется. Если APC помещается в очередь в поток, функция не возвращается немедленно и функция APC не выполняется.

Если параметр имеет значение TRUE, а поток, который вызвал эту функцию, является тем же потоком, который вызвал функцию расширенного ввода-вывода (ReadFileEx или WriteFileEx), функция возвращается по истечении времени ожидания или при выполнении функции обратного вызова завершения ввода-вывода. Если выполняется обратный вызов завершения ввода-вывода, вызывается функция завершения ввода-вывода. Если APC помещается в очередь в поток (QueueUserAPC), функция возвращается по истечении времени ожидания или при вызове функции APC.

Возвращаемое значение

Возвращаемое значение равно нулю, если истек указанный интервал времени.

Возвращаемое значение WAIT_IO_COMPLETION , если функция возвращается из-за одной или нескольких функций обратного вызова завершения ввода-вывода. Это может произойти, только если параметр bAlertable имеет значение TRUE, а поток, который вызвал функцию SleepEx , является тем же потоком, который вызвал расширенную функцию ввода-вывода.

Эта функция приводит к тому, что поток откажется от оставшейся части своего среза времени и становится неисполнимым в течение интервала, основанного на значении dwMilliseconds. После прохождения интервала спящего режима поток готов к запуску. Обратите внимание, что готовый поток не гарантирует немедленного запуска. Следовательно, поток не будет выполняться до некоторого произвольного времени после истечения интервала спящего режима на основе системной "тактовой" частоты и коэффициента нагрузки от других процессов. Системные часы "тикают" с постоянной скоростью. Чтобы повысить точность интервала спящего режима, вызовите функцию timeGetDevCaps , чтобы определить поддерживаемую минимальное разрешение таймера, и функцию timeBeginPeriod , чтобы задать минимальное разрешение таймера. Будьте осторожны при вызове timeBeginPeriod, так как частые вызовы могут значительно повлиять на системные часы, энергопотребление системы и планировщик. Если вы вызываете timeBeginPeriod, вызовите его один раз в начале приложения и обязательно вызовите функцию timeEndPeriod в самом конце приложения. Если указать 0 миллисекунд, поток откажется от оставшейся части времени, но останется готовым. Дополнительные сведения см. в разделе Приоритеты планирования.

Эту функцию можно использовать с функциями ReadFileEx или WriteFileEx для приостановки потока до завершения операции ввода-вывода. Эти функции определяют подпрограмму завершения, которая должна выполняться после завершения операции ввода-вывода. Для выполнения подпрограммы завершения поток, который вызвал функцию ввода-вывода, должен находиться в состоянии ожидания с возможностью предупреждения при возникновении функции обратного вызова завершения. Поток переходит в состояние ожидания с оповещением, вызывая SleepEx, MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx или WaitForMultipleObjectsEx с параметром bAlertable функции, равным TRUE.

Будьте внимательны при использовании SleepEx в следующих сценариях:

Код, который прямо или косвенно создает окна (например, DDE и COM CoInitialize). Если поток создает какие-либо окна, он должен обрабатывать сообщения. Широковещательные сообщения отправляются во все окна в системе. Если у вас есть поток, использующий SleepEx с бесконечной задержкой, система будет взаимоблокировкой.
Потоки, которые находятся под контролем параллелизма. Например, порт завершения ввода-вывода или пул потоков ограничивает количество связанных потоков, которые могут выполняться. Если максимальное количество потоков уже запущено, дополнительный связанный поток не может выполняться до завершения выполняющегося потока. Если поток использует SleepEx с нулевым интервалом для ожидания выполнения определенной работы одним из дополнительных связанных потоков, процесс может оказаться взаимоблокировкой.

В этих сценариях используйте MsgWaitForMultipleObjects или MsgWaitForMultipleObjectsEx, а не SleepEx.

Windows Phone 8.1. Эта функция поддерживается для приложений магазина Windows Phone в Windows Phone 8.1 и более поздних версий.

Windows 8.1 и Windows Server 2012 R2: эта функция поддерживается для приложений Магазина Windows на Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	synchapi.h (включая Windows.h в Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Библиотека	Kernel32.lib; WindowsPhoneCore.lib на Windows Phone 8.1
DLL	KernelBase.dll Windows Phone 8.1; Kernel32.dll