展开 最小化

KeWaitForMutexObject routine

The KeWaitForMutexObject routine puts the current thread into an alertable or nonalertable wait state until the given mutex object is set to a signaled state or (optionally) until the wait times out.

Syntax


NTSTATUS KeWaitForMutexObject(
  _In_      PVOID Mutex,
  _In_      KWAIT_REASON WaitReason,
  _In_      KPROCESSOR_MODE WaitMode,
  _In_      BOOLEAN Alertable,
  _In_opt_  PLARGE_INTEGER Timeout
);

Parameters

Mutex [in]

Pointer to an initialized mutex object for which the caller supplies the storage.

WaitReason [in]

Specifies the reason for the wait, which should be set to Executive. If the driver is doing work on behalf of a user and is running in the context of a user thread, this parameter should be set to UserRequest.

WaitMode [in]

The caller must specify KernelMode.

Alertable [in]

Specifies a Boolean value that indicates whether the wait is alertable.

Timeout [in, optional]

Pointer to a time-out value that specifies the absolute or relative time, in 100-nanosecond units, at which the wait is to be completed.

A positive value specifies an absolute time, relative to January 1, 1601. A negative value specifies an interval relative to the current time. Absolute expiration times track any changes in the system time; relative expiration times are not affected by system time changes.

If *Timeout = 0, the routine returns without waiting. If the caller supplies a NULL pointer, the routine waits indefinitely until the mutex object is set to the signaled state. For more information, see the following Remarks section.

Return value

KeWaitForMutexObject can return one of the following:

Return codeDescription
STATUS_SUCCESS

The dispatcher object specified by the Mutex parameter satisfied the wait.

STATUS_ALERTED

The wait was interrupted to deliver an alert to the calling thread.

STATUS_USER_APC

The wait was interrupted to deliver a user asynchronous procedure call (APC) to the calling thread.

STATUS_TIMEOUT

A time-out occurred before the mutex was set to a signaled state. This value can be returned when an explicit time-out value of zero is specified and the specified set of wait conditions cannot be immediately met.

 

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

Remarks

KeWaitForMutexObject is a macro that converts to KeWaitForSingleObject, which can be used instead.

For better performance, use fast mutexes or guarded mutexes. For more information, see Alternatives to Mutex Objects.

For more information about how to use this routine, see KeWaitForSingleObject.

For more information about mutex objects, see Mutex Objects.

A mutex can be recursively acquired only MINLONG times. If this limit is exceeded, the routine raises a STATUS_MUTANT_LIMIT_EXCEEDED exception.

Callers of KeWaitForMutexObject must be running at IRQL <= DISPATCH_LEVEL. However, if Timeout = NULL or *Timeout != 0, the caller must be running at IRQL <= APC_LEVEL and in a nonarbitrary thread context. (If Timeout != NULL and *Timeout = 0, the caller must be running at IRQL <= DISPATCH_LEVEL.)

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

See Remarks section.

DDI compliance rules

HwStorPortProhibitedDDIs, SpNoWait, StorPortStartIo

See also

ExAcquireFastMutex
ExAcquireFastMutexUnsafe
ExInitializeFastMutex
KeBugCheckEx
KeInitializeMutex
KeReadStateMutex
KeReleaseMutex

 

 

Send comments about this topic to Microsoft

显示:
© 2014 Microsoft