Функция ZwWaitForSingleObject (ntifs.h)

Статья
07/11/2023

Подпрограмма ZwWaitForSingleObject ожидает, пока указанный объект не достигнет состояния Signaled. Также можно указать дополнительное время ожидания.

Синтаксис

NTSYSAPI NTSTATUS ZwWaitForSingleObject(
  [in]           HANDLE         Handle,
  [in]           BOOLEAN        Alertable,
  [in, optional] PLARGE_INTEGER Timeout
);

Параметры

[in] Handle

Дескриптор объекта .

[in] Alertable

Логическое значение, указывающее, является ли ожидание оповещенным.

[in, optional] Timeout

Необязательный указатель на значение времени ожидания, указывающее абсолютное или относительное время ожидания. Отрицательное значение указывает интервал относительно текущего времени. Значение должно быть выражено в единицах 100 наносекунд. Абсолютное время истечения срока действия отслеживает любые изменения системного времени. Изменения системного времени не влияют на относительный срок действия.

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

ZwWaitForSingleObject может возвращать один из следующих возможных кодов состояния:

Код возврата	Описание
STATUS_ACCESS_DENIED	Вызывающий объект не имеет необходимых привилегий для события, указанного параметром Handle .
STATUS_ALERTED	Ожидание прервано, чтобы доставить оповещение в текущий поток.
STATUS_INVALID_HANDLE	Предоставленный параметр Handle был недопустимым.
STATUS_SUCCESS	Указанный объект выполнил ожидание.
STATUS_TIMEOUT	Время ожидания истекло до того, как объект был установлен в состояние сигнала. Это значение может быть возвращено, если не удается немедленно выполнить указанный набор условий ожидания, а для параметра Timeout задано значение 0.
STATUS_USER_APC	Ожидание прервано для доставки пользовательского APC в текущий поток.

Обратите внимание, что макрос NT_SUCCESS распознает значения состояния STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT и STATUS_USER_APC как "успешно".

ZwWaitForSingleObject ожидает, пока указанный объект не достигнет состояния Signaled. Также можно указать дополнительное время ожидания. ZwWaitForSingleObject проверяет текущее состояние указанного объекта, чтобы определить, можно ли выполнить ожидание немедленно. Если это так, выполняются действия. В противном случае текущий поток переводится в состояние ожидания и выбирается новый поток для выполнения на текущем процессоре.

Если параметр Timeout не указан, ожидание не будет удовлетворено, пока объект не достигнет состояния Signaled. Если указан параметр Timeout и объект не достиг состояния Signaled по истечении времени ожидания, ожидание выполняется автоматически. Если указано явное значение времени ожидания , равное нулю, ожидание не будет выполнено, если ожидание не может быть выполнено немедленно. Нулевое значение времени ожидания позволяет проверить набор условий ожидания и условную производительность любых побочных эффектов, если ожидание может быть немедленно выполнено, как при приобретении мьютекса. Ожидание также можно указать в качестве оповещенного.

Параметр Alertable указывает, можно ли оповещать поток и его состояние ожидания, следовательно, прервано. Если этот параметр имеет значение FALSE, оповещение о потоке невозможно. Единственным исключением из этого правила является завершающий поток. При определенных обстоятельствах завершающийся поток может быть оповещен, пока он находится в процессе сматки. Поток автоматически становится оповещенным, например при завершении пользователем с помощью клавиш CTRL+C.

Если значение Alertableравно TRUE и присутствует одно из следующих условий, поток будет оповещен:

Если источником оповещения является внутренняя недокументированная подпрограмма режима ядра, используемая для потоков оповещений.
Источником оповещения является APC в пользовательском режиме.

В первом из этих двух случаев ожидание потока удовлетворяется состоянием завершения STATUS_ALERTED. Во втором случае он удовлетворяется состоянием завершения STATUS_USER_APC.

Поток должен быть оповещен для доставки APC в пользовательском режиме. Это не относится к APC в режиме ядра. APC в режиме ядра может быть доставлен и выполнен, даже если поток не оповещен. После завершения выполнения APC ожидание потока возобновляется. Поток никогда не оповещается, а его ожидание не прерывается доставкой APC в режиме ядра.

Доставка APC в режиме ядра в ожидающий поток не зависит от того, можно ли оповещать поток. Если APC в режиме ядра является специальным APC в режиме ядра, то APC доставляется при условии, что IRQL меньше APC_LEVEL. Если APC в режиме ядра является обычным APC в режиме ядра, то APC доставляется при условии, что выполняется три следующих условия: (1) IRQL меньше APC_LEVEL, (2) не выполняется APC ядра, и (3) поток не находится в критическом разделе.

Если дескриптор, передаваемый в ZwWaitForSingleObject , относится к мьютексу, доставка APC будет такой же, как и для всех других объектов диспетчера во время ожидания. Однако после того, как ZwWaitForSingleObject возвращает с STATUS_SUCCESS, а поток фактически содержит мьютекс, доставляются только специальные APC режима ядра. Доставка всех остальных APC, как в режиме ядра, так и в пользовательском режиме, отключена. Это ограничение на доставку APC сохраняется до тех пор, пока мьютекс не будет освобожден.

Особенно важно проверка возвращаемое значение ZwWaitForSingleObject, если параметр Alertable имеет значение TRUE, так как ZwWaitForSingleObject может вернуться рано с состоянием STATUS_USER_APC или STATUS_ALERTED.

Все длительные ожидания могут быть прерваны пользователем, если параметру Alertable задано значение FALSE.

Дополнительные сведения см. в статье Получение оповещений и api-интерфейсов в потоках ожидания?

Вызывающие объекты ZwWaitForSingleObject должны выполняться в IRQL меньше или равно DISPATCH_LEVEL. Как правило, вызывающий объект должен выполняться в PASSIVE_LEVEL IRQL и в контексте неарбитарного потока. Вызов во время выполнения в DISPATCH_LEVEL IRQL действителен, если и только в том случае, если вызывающий объект задает параметр timeout , равный нулю. То есть драйвер не должен ждать ненулевого интервала в IRQL, равном DISPATCH_LEVEL.

Интервалы времени ожидания измеряются относительно системных часов, а точность измерения времени ожидания ограничивается степенью детализации системных часов. Дополнительные сведения см. в разделе Точность таймера.

Если вызов функции ZwWaitForSingleObject выполняется в пользовательском режиме, следует использовать имя "NtWaitForSingleObject" вместо "ZwWaitForSingleObject".

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы Собственные системные службы Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями подпрограмм NtXxx и ZwXxx см. в разделе Использование версий NT и Zw подпрограмм собственных системных служб.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h, FltKernel.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), SpNoWait(storport)