KeDelayExecutionThread

The KeDelayExecutionThread routine puts the current thread into an alertable or nonalertable wait state for a given interval.

NTSTATUS 
  KeDelayExecutionThread(
    IN KPROCESSOR_MODE  WaitMode,
    IN BOOLEAN  Alertable,
    IN PLARGE_INTEGER  Interval
    );

Parameters

WaitMode

Specifies the processor mode in which the caller is waiting, which can be either KernelMode or UserMode. Lower-level drivers should specify KernelMode.

Alertable

Specifies TRUE if the wait is alertable. Lower-level drivers should specify FALSE.

Interval

Specifies the absolute or relative time, in units of 100 nanoseconds, for which the wait is to occur. A negative value indicates relative time. Absolute expiration times track any changes in system time; relative expiration times are not affected by system time changes.

Headers

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

Return Value

KeDelayExecutionThread returns one of the following values that describes how the delay was completed:

STATUS_SUCCESS

The delay completed because the specified interval elapsed.

STATUS_ALERTED

The delay completed because the thread was alerted.

STATUS_USER_APC

A user-mode APC was delivered before the given Interval expired.

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

Comments

The expiration time is computed and the current thread is put in a wait state. When the specified interval has passed, the thread exits the wait state and is put in the ready state, becoming eligible for execution.

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 is present, the thread will be alerted:

1. If the origin of the alert is an internal, undocumented kernel-mode routine used to alert threads.
2. 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 resumes. 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 thread that has called KeDelayExecutionThread does not depend on whether the thread can be alerted. 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-mode APC is in progress, and(3) the thread is not in a critical section.

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 KeDelayExecutionThread using the UserMode argument.

It is especially important to check the return value of KeDelayExecutionThread when the WaitMode parameter is UserMode or Alertable is TRUE, because KeDelayExecutionThread 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.

The expiration time of the delay is expressed as either an absolute time at which the delay is to expire, or a time relative to the current system time. If the Interval parameter is a negative value, the expiration time is relative.

Callers of KeDelayExecutionThread must be running at IRQL = PASSIVE_LEVEL.

See Also

KeQuerySystemTime