KeWaitForMultipleObjects

KeWaitForMultipleObjects

NTSTATUS
KeWaitForMultipleObjects(
IN ULONG Count,
IN PVOID Object[],
IN WAIT_TYPE WaitType,
IN KWAIT_REASON WaitReason,
IN KPROCESSOR_MODE WaitMode,
IN BOOLEAN Alertable,
IN PLARGE_INTEGER Timeout,/* optional */
IN PKWAIT_BLOCK WaitBlockArray /* optional */
);

KeWaitForMultipleObjects puts the current thread into an alertable or nonalertable wait state until any or all of a number of dispatcher objects are set to the Signaled state or (optionally) until the wait times out.

Parameters

Count

Specifies the number of objects to be waited on.

Object

Points to an array of pointers to dispatcher objects (events, mutexes, semaphores, threads, and timers) for which the caller supplies the storage.

WaitType

Specifies either WaitAll, indicating that all of the specified objects must attain a state of Signaled before the wait is satisfied, or WaitAny, indicating that any one of the objects must attain a state of Signaled before the wait is satisfied.

WaitReason

Specifies the reason for the wait. Drivers should set this value to Executive or, if the driver is doing work on behalf of a user and is running in the context of a User thread, to UserRequest.

WaitMode

Specifies whether the caller waits in KernelMode or UserMode. Intermediate and lowest level drivers should specify KernelMode. If the set of objects waited on includes a mutex, the caller must specify KernelMode.

Alertable

Specifies a Boolean value that indicates whether the thread can be alerted while it is in the waiting state.

Timeout

Points to an absolute or relative value representing the upper limit for the wait. A negative value specifies an interval relative to the current system time. The value should be expressed in units of 100 nanoseconds. Absolute expiration times track any changes in the system time; relative expiration times are not affected by system time changes.

WaitBlockArray

Points to an optional array of Wait blocks that describe the Wait operation.

Return Value

KeWaitForMultipleObjects can return one of the following NTSTATUS values:

Value	Meaning
STATUS_SUCCESS	Depending on the specified WaitType, one or all of the dispatcher objects in the Object array satisfied the wait.
STATUS_ALERTED	The wait is completed because of an alert to the thread.
STATUS_USER_APC	A user APC was delivered to the current thread before the specified Timeout interval expired.
STATUS_TIMEOUT	A time-out occurred before the specified set of wait conditions was met. This value can be returned when an explicit time-out value of zero is specified, but the specified set of wait conditions cannot be met immediately.

If KeWaitForMultipleObjects returns STATUS_SUCCESS and if WaitAny is specified as the WaitType, KeWaitForMultipleObjects also returns the zero-based index of the object that satisfied the wait at NTSTATUS.

Comments

Each thread object has a built-in array of wait blocks that can be used to wait on several objects concurrently. Whenever possible, the built-in array of wait blocks should be used in a wait-multiple operation because no additional wait block storage need be allocated and later deallocated. However, if the number of objects to be waited on concurrently is greater than the number of built-in wait blocks, use the WaitBlockArray parameter to specify an alternate set of wait blocks to be used in the wait operation.

If the WaitBlockArray parameter is NULL, the Count parameter must be less than or equal to THREAD_WAIT_OBJECTS or a bug check will occur.

If the WaitBlockArray pointer is nonNULL, the Count parameter must be less than or equal to MAXIMUM_WAIT_OBJECTS or a bug check will occur.

The current state for each of the specified objects is examined to determine whether the wait can be satisfied immediately. If the necessary side effects are performed on the objects, an appropriate value is returned.

If the wait cannot be satisfied immediately and either no time-out value or a nonzero time-out value has been specified, the current thread is put in a waiting state and a new thread is selected for execution on the current processor. If no Timeout is supplied, the calling thread will remain in a Wait state until the conditions specified by Object and WaitType are satisfied.

If Timeout is specified, the wait will be automatically satisfied if none of the specified wait conditions is met when the given interval expires.

A Timeout value of zero allows the testing of a set of wait conditions, conditionally performing any side effects if the wait can be immediately satisfied, as in the acquisition of a mutex.

The Alertable parameter specifies whether the thread can be alerted in the wait state. If the value of this parameter is TRUE and the thread is alerted for a mode that is equal to or more privileged than the given WaitMode, the thread's wait will be satisfied with a completion status of STATUS_ALERTED.

If the WaitMode parameter is UserMode and the Alertable parameter is TRUE, the thread can also be awakened to deliver a user-mode APC. Kernel-mode APCs always cause the subject thread to be awakened if the wait IRQL is PASSIVE_LEVEL and no kernel APC is in progress.

Callers of KeWaitForMultipleObjects can be running at IRQL <= DISPATCH_LEVEL. However, the caller cannot wait at raised IRQL for a nonzero interval nor in an arbitrary thread context on any dispatcher object, so callers usually are running at IRQL PASSIVE_LEVEL. A call while running at IRQL DISPATCH_LEVEL is valid if and only if the caller specifies a Timeout of zero. That is, a driver must not wait for a nonzero interval at IRQL DISPATCH_LEVEL.