KeWaitForMultipleObjects

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

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
    );

Parameters

Count: Specifies the number of objects to be waited on.
Object: Pointer 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 signaled state before the wait is satisfied; or WaitAny, indicating that any one of the objects must attain a signaled state 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: Pointer 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: If Count <= THREAD_WAIT_OBJECTS, then WaitBlockArray can be NULL. Otherwise this parameter must point to a memory buffer of sizeof(KWAIT_BLOCK) * Count bytes. The routine uses this buffer for record-keeping while performing the wait operation.

Return Value

KeWaitForMultipleObjects can return one of the following:

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.

Note that the NT_SUCCESS macro recognizes all of these status values as "success" values.

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.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

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 needs to be allocated and later deallocated. However, if the number of objects that must 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. Drivers only need to allocate a sufficiently-large memory buffer for WaitBlockArray. The buffer does not need to be initialized, and the drivers can treat it as an opaque structure. The buffer can be freed once the routine returns.

If either Count > MAXIMUM_WAIT_OBJECTS or if WaitBlockArray is NULL and Count > THREAD_WAIT_OBJECTS, the system issues Bug Check 0xC (MAXIMUM_WAIT_OBJECTS_EXCEEDED).

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 and its wait state consequently aborted. If the value of this parameter is FALSE then the thread cannot be alerted, no matter what the value of the WaitMode parameter or the origin of the alert. The only exception to this rule is that of a terminating thread. A thread is automatically made alertable, for instance, when terminated by a user with a CTRL+C.

If the value of Alertable is TRUE and one of the following conditions exists, the thread will be alerted:

If the origin of the alert is an internal, undocumented kernel-mode routine used to alert threads.
If the origin of the alert is a user-mode APC and the value of the WaitMode parameter is UserMode.

In the first of these two cases, the thread’s wait is satisfied with a completion status of STATUS_ALERTED; in the second case, it is satisfied with a completion status of STATUS_USER_APC.

The thread must be alertable for a user-mode APC to be delivered. This is not the case for kernel-mode APCs. A kernel-mode APC can be delivered and executed even though the thread is not alerted. Once the APC's execution completes, the thread's wait will resume. A thread is never alerted nor is its wait aborted by the delivery of a kernel-mode APC.

The delivery of kernel-mode APCs to a waiting thread does not depend on whether the thread can be alerted, but it depends on other conditions. If the kernel-mode APC is a special kernel-mode APC, then the APC is delivered provided that IRQL < APC_LEVEL. If the kernel-mode APC is a normal kernel-mode APC, then the APC is delivered provided that the following three conditions hold: (1) IRQL < APC_LEVEL, (2) no kernel APC is in progress, and (3) the thread is not in a critical section.

A special consideration applies when the Object parameter passed to KeWaitForMultipleObjects is a mutex. If the dispatcher object waited on is a mutex, APC delivery is the same as for all other dispatcher objects during the wait. However, once KeWaitForMultipleObjects returns with STATUS_SUCCESS and the thread actually holds the mutex, only special kernel-mode APCs are delivered. Delivery of all other APCs, both kernel-mode and user-mode, is disabled. This restriction on the delivery of APCs persists until the mutex is released.

For additional information, see Do Waiting Threads Receive Alerts and APCs?

If the WaitMode parameter is UserMode, the kernel stack can be swapped out during the wait. Consequently, a caller must never attempt to pass parameters on the stack when calling KeWaitForMultipleObjects with the UserMode argument. If you allocate the event on the stack, you must set the WaitMode parameter to KernelMode.

It is especially important to check the return value of KeWaitForMultipleObjects when the WaitMode parameter is UserMode or Alertable is TRUE, because KeWaitForMultipleObjects might return early with a status of STATUS_USER_APC or STATUS_ALERTED.

All long term waits that can be aborted by a user should be UserMode waits and Alertable should be set to FALSE.

Where possible, Alertable should be set to FALSE and WaitMode should be set to KernelMode, in order to reduce driver complexity. The principal exception to this is when the wait is a long term wait.

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. Therefore 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.

KeWaitForMultipleObjects

Parameters

Return Value

Headers

Comments

See Also