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

Статья
12/21/2024

FsRtlCancellableWaitForMultipleObjects подпрограмма выполняет отменяемую операцию ожидания (ожидание, которое может быть завершено) для одного или нескольких объектов диспетчера.

Синтаксис

NTSTATUS FsRtlCancellableWaitForMultipleObjects(
  [in]           ULONG          Count,
  [in]           PVOID []       ObjectArray,
  [in]           WAIT_TYPE      WaitType,
  [in, optional] PLARGE_INTEGER Timeout,
  [in, optional] PKWAIT_BLOCK   WaitBlockArray,
  [in, optional] PIRP           Irp
);

Параметры

[in] Count

Количество объектов, которые нужно ожидать.

[in] ObjectArray

Указатель на массив указателей на объекты диспетчера (события, мьютексы, семафоры, потоки и таймеры), для которых вызывающий объект предоставляет хранилище.

[in] WaitType

Либо WaitAll, то есть все указанные объекты должны достичь сигнального состояния, прежде чем ожидание будет удовлетворено; или WaitAny, что означает, что любой из объектов должен достичь сигнального состояния перед выполнением ожидания.

[in, optional] Timeout

Указатель на необязательное значение времени ожидания. Этот параметр указывает абсолютное или относительное время в 100 единицх наносеконд, в которых ожидается завершение ожидания.

Если время ожидания указывает на нулевое значение (то есть *время ожидания == 0), подпрограмма возвращается без ожидания. Если вызывающий объект предоставляет указатель NULL (т. е. время ожидания время ожидания == NULL), подпрограмма ожидает неограниченное время до тех пор, пока все объекты диспетчера не будут заданы сигнальным состоянием.

Положительное значение указывает абсолютное время относительно 1 января 1601 года. Отрицательное значение указывает интервал относительно текущего времени. Абсолютное время истечения срока действия отслеживает любые изменения в системном времени; относительные сроки действия не влияют на изменения системного времени.

Если указано время ожидания, ожидание будет автоматически удовлетворено, если ни одно из указанных условий ожидания не будет выполнено при истечении заданного интервала.

Значение времени ожидания (т. е. *Timeout == 0) позволяет протестировать набор условий ожидания и условно выполнить любые дополнительные действия, если ожидание может быть немедленно удовлетворено, как при приобретении мьютекса.

[in, optional] WaitBlockArray

Если Count<= THREAD_WAIT_OBJECTS, WaitBlockArray может иметь значение NULL. В противном случае этот параметр должен указывать на буфер памяти sizeof(KWAIT_BLOCK * Count) байтов. Подпрограмма использует этот буфер для хранения записей при выполнении операции ожидания.

[in, optional] Irp

Указатель на исходный IRP, соответствующий операции ввода-вывода, выданной пользователем, и его можно отменить. Вызывающий объект должен убедиться, что IRP будет оставаться действительным в течение этой процедуры, и что IRP не должен иметь набор подпрограмм отмены (например, IoSetCancelRoutine не должны вызываться для IRP). Обратите внимание, что IRP должен храниться вызывающим оператором, он не может быть передан драйверу нижнего уровня.

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

FsRtlCancellableWaitForMultipleObjects может возвращать одно из следующих значений:

Возвращаемый код	Описание
STATUS_SUCCESS	Вызывающий объект, указанный WaitAll для параметра WaitType, а все объекты диспетчера в массиве ObjectArray заданы в сигнальном состоянии.
STATUS_TIMEOUT	Время ожидания произошло до выполнения указанного набора условий ожидания. Это значение можно вернуть, если указанный набор условий ожидания не может быть немедленно выполнен и время ожидания равно нулю.
STATUS_WAIT_0 через STATUS_WAIT_63	Вызывающий объект, указанный WaitAny для WaitType, а для одного из объектов диспетчера в массиве ObjectArray задано сигнальное состояние. Ниже шесть битов возвращаемого значения кодируют отсчитываемый от нуля индекс объекта, удовлетворяющий ожиданию.
STATUS_ABANDONED_WAIT_0 through STATUS_ABANDONED_WAIT_63	Вызывающий попытался ждать мьютекса, который был заброшен. Более низкие шесть битов возвращаемого значения кодируют отсчитываемый от нуля индекс мьютекса в массиве ObjectArray.
STATUS_CANCELLED	Ожидание было прервано запросом на отмену по указанному IRP. Обратите внимание, что это значение возвращается только в том случае, если допустимый IRP передается FsRtlCancellableWaitForMultipleObjects и IRP был отменен CancelSynchronousIo.
STATUS_THREAD_IS_TERMINATING	Ожидание было прервано, так как поток был завершен приложением или пользователем.

Возвращаемое значение указывает только состояние ожидания. Если применимо, фактическое состояние запроса ввода-вывода должно быть получено непосредственно из другого IRP, созданного в процессе обработки исходного пользовательского интерфейса IRP.

Обратите внимание, что макрос NT_SUCCESS возвращает значение FALSE ("сбой") для STATUS_CANCELLED и STATUS_THREAD_IS_TERMINATING значений состояния и TRUE ("успешно") для всех остальных значений состояния.

Замечания

FsRtlCancellableWaitForMultipleObjects подпрограмма выполняет отменяемую операцию ожидания для объектов диспетчера. Если поток завершается пользователем или приложением, или если CancelSynchronousIo отправляет запрос отмены на потоковый IRP (синхронный IRP), связанный с потоком, ожидание отменяется.

Подпрограмма FsRtlCancellableWaitForMultipleObjects была разработана для поддержки рекомендаций по завершению и отмене ввода-вывода начиная с Windows Vista. Цель этих рекомендаций — разрешить пользователям (или приложениям) быстро завершать работу приложений. Это, в свою очередь, требует, чтобы приложения имели возможность быстро завершать потоки, выполняющие операции ввода-вывода, а также любые текущие операции ввода-вывода. Эта подпрограмма позволяет пользовательским потокам блокировать (т. е. ждать) в ядре для завершения ввода-вывода, объектов диспетчера или переменных синхронизации таким образом, чтобы ждать будет легко отменено. Эта подпрограмма также позволяет завершить ожидание потока, если поток завершается пользователем или приложением.

Например, перенаправление может потребоваться создать одну или несколько вторичных IRP, чтобы обработать IRP в пользовательском режиме и синхронно ожидать завершения дополнительных IRP. Одним из способов этого является настройка события, которое будет сигнализировать подпрограммой завершения вторичного IRP, а затем ждать, пока событие будет сигнализировать. Затем для выполнения операции отмены ожидания FsRtlCancellableWaitForMultipleObjects вызывает передачу события, связанного с вторичным IRP, а также исходного пользовательского режима IRP. Ожидается, что событие будет отменено, если событие ожидает завершения или если исходный IRP в пользовательском режиме отменен.

Обратите внимание, что завершение ожидания не отменяет автоматическую операцию ввода-вывода, выданную вызывающим оператором, которая должна обрабатываться отдельно вызывающим оператором.

Каждый объект потока имеет встроенный массив блоков ожидания, который можно использовать для одновременного ожидания нескольких объектов. По возможности встроенный массив блоков ожидания следует использовать в операции ожидания с несколькими ожиданиями, так как дополнительное хранилище блоков ожидания не должно быть выделено и более поздней сделки. Однако если количество объектов, которые необходимо ожидать одновременно, больше количества встроенных блоков ожидания, используйте параметр WaitBlockArray, чтобы указать альтернативный набор блоков ожидания, используемый в операции ожидания. Драйверам необходимо выделить достаточно большой буфер памяти для WaitBlockArray. Буфер не нужно инициализировать, и драйверы могут рассматривать его как непрозрачную структуру. Буфер можно освободить после возврата подпрограммы.

Если число больше MAXIMUM_WAIT_OBJECTS или если WaitBlockArray значение NULL и число больше THREAD_WAIT_OBJECTS, системные проблемы проверки ошибок 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED.

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

Мьютекс может быть рекурсивно приобретен только во время MINLONG. Если это ограничение превышено, подпрограмма вызывает исключение STATUS_MUTANT_LIMIT_EXCEEDED.

FsRtlCancellableWaitForMultipleObjects должен вызываться в IRQL PASSIVE_LEVEL, если необязательный параметр Irp указывает на допустимый IRP. Если параметр Irp не используется, подпрограмма может вызываться в IRQL меньше или равно APC_LEVEL. При необходимости обычные API ядра можно отключить вызывающим оператором, вызвав подпрограммы KeEnterCriticalRegion или FsRtlEnterFileSystem. Однако специальные API ядра не должны быть отключены.

FsRtlCancellableWaitForMultipleObjects будет утверждаться при отладке сборок, если IRQL больше или равно APC_LEVEL, а параметр irp указывает на допустимый IRP.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista
целевая платформа	Всеобщий
заголовка	ntifs.h (include Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	См. раздел "Примечания".
правил соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm), SpNoWait(storport)