KeAcquireInStackQueuedSpinLock function (wdm.h)

The KeAcquireInStackQueuedSpinLock routine acquires a queued spin lock.

Syntax

void KeAcquireInStackQueuedSpinLock(
  PKSPIN_LOCK         SpinLock,
  PKLOCK_QUEUE_HANDLE LockHandle
);

Parameters

SpinLock

[in, out] Specifies the spin lock to acquire. This parameter must have been initialized with KeInitializeSpinLock.

LockHandle

[out] A pointer to a caller-supplied KLOCK_QUEUE_HANDLE variable that the routine can use to return the spin lock queue handle. The caller passes this value to KeReleaseInStackQueuedSpinLock when releasing the lock. Drivers should normally allocate the structure on the stack each time they acquire the lock. A driver should not use the same KLOCK_QUEUE_HANDLE from multiple calling sites.

Return value

None

Remarks

KeAcquireInStackQueuedSpinLock acquires a spin lock as a queued spin lock. For more information, see Queued Spin Locks. The caller releases the spin lock by calling the KeReleaseInStackQueuedSpinLock routine.

Like ordinary spin locks, queued spin locks must only be used in very special circumstances. For a description of when to use spin locks, see KeAcquireSpinLock.

This routine raises the IRQL level to DISPATCH_LEVEL when acquiring the spin lock. If the caller is guaranteed to already be running at DISPATCH_LEVEL, it is more efficient to call KeAcquireInStackQueuedSpinLockAtDpcLevel.

The call to KeReleaseInStackQueuedSpinLock that releases the spin lock must occur at IRQL = DISPATCH_LEVEL. This call restores the original IRQL that the operating system saved at the beginning of the KeAcquireInStackQueuedSpinLock call.

Drivers must not combine calls to KeAcquireSpinLock and KeAcquireInStackQueuedSpinLock on the same spin lock. A spin lock must always be acquired or released as either a queued spin lock, or as an ordinary spin lock.

Requirements

See also

KLOCK_QUEUE_HANDLE

KeAcquireInStackQueuedSpinLockAtDpcLevel

KeAcquireSpinLock

KeInitializeSpinLock

KeReleaseInStackQueuedSpinLock