queuedlock.c File Reference

#include <phbase.h>
#include <phintrnl.h>

Go to the source code of this file.

Functions
VOID FASTCALL	PhpfOptimizeQueuedLockList (_Inout_ PPH_QUEUED_LOCK QueuedLock, _In_ ULONG_PTR Value)
	Optimizes a queued lock waiters list.
VOID FASTCALL	PhpfWakeQueuedLock (_Inout_ PPH_QUEUED_LOCK QueuedLock, _In_ ULONG_PTR Value)
	Wakes waiters in a queued lock.
VOID FASTCALL	PhpfWakeQueuedLockEx (_Inout_ PPH_QUEUED_LOCK QueuedLock, _In_ ULONG_PTR Value, _In_ BOOLEAN IgnoreOwned, _In_ BOOLEAN WakeAll)
	Wakes waiters in a queued lock.
BOOLEAN	PhQueuedLockInitialization (VOID)
FORCEINLINE BOOLEAN	PhpPushQueuedWaitBlock (_Inout_ PPH_QUEUED_LOCK QueuedLock, _In_ ULONG_PTR Value, _In_ BOOLEAN Exclusive, _Out_ PPH_QUEUED_WAIT_BLOCK WaitBlock, _Out_ PBOOLEAN Optimize, _Out_ PULONG_PTR NewValue, _Out_ PULONG_PTR CurrentValue)
	Pushes a wait block onto a queued lock's waiters list.
FORCEINLINE PPH_QUEUED_WAIT_BLOCK	PhpFindLastQueuedWaitBlock (_In_ ULONG_PTR Value)
	Finds the last wait block in the waiters list.
_May_raise_ FORCEINLINE NTSTATUS	PhpBlockOnQueuedWaitBlock (_Inout_ PPH_QUEUED_WAIT_BLOCK WaitBlock, _In_ BOOLEAN Spin, _In_opt_ PLARGE_INTEGER Timeout)
	Waits for a wait block to be unblocked.
_May_raise_ FORCEINLINE VOID	PhpUnblockQueuedWaitBlock (_Inout_ PPH_QUEUED_WAIT_BLOCK WaitBlock)
	Unblocks a wait block.
FORCEINLINE VOID	PhpOptimizeQueuedLockListEx (_Inout_ PPH_QUEUED_LOCK QueuedLock, _In_ ULONG_PTR Value, _In_ BOOLEAN IgnoreOwned)
	Optimizes a queued lock waiters list.
FORCEINLINE PPH_QUEUED_WAIT_BLOCK	PhpPrepareToWakeQueuedLock (_Inout_ PPH_QUEUED_LOCK QueuedLock, _In_ ULONG_PTR Value, _In_ BOOLEAN IgnoreOwned, _In_ BOOLEAN WakeAll)
	Dequeues the appropriate number of wait blocks in a queued lock.
VOID FASTCALL	PhfAcquireQueuedLockExclusive (_Inout_ PPH_QUEUED_LOCK QueuedLock)
	Acquires a queued lock in exclusive mode.
VOID FASTCALL	PhfAcquireQueuedLockShared (_Inout_ PPH_QUEUED_LOCK QueuedLock)
	Acquires a queued lock in shared mode.
VOID FASTCALL	PhfReleaseQueuedLockExclusive (_Inout_ PPH_QUEUED_LOCK QueuedLock)
	Releases a queued lock in exclusive mode.
VOID FASTCALL	PhfReleaseQueuedLockShared (_Inout_ PPH_QUEUED_LOCK QueuedLock)
	Releases a queued lock in shared mode.
VOID FASTCALL	PhfTryWakeQueuedLock (_Inout_ PPH_QUEUED_LOCK QueuedLock)
	Wakes waiters in a queued lock, making no assumptions about the state of the lock.
VOID FASTCALL	PhfWakeForReleaseQueuedLock (_Inout_ PPH_QUEUED_LOCK QueuedLock, _In_ ULONG_PTR Value)
	Wakes waiters in a queued lock for releasing it in exclusive mode.
VOID FASTCALL	PhfPulseCondition (_Inout_ PPH_QUEUED_LOCK Condition)
	Wakes one thread sleeping on a condition variable.
VOID FASTCALL	PhfPulseAllCondition (_Inout_ PPH_QUEUED_LOCK Condition)
	Wakes all threads sleeping on a condition variable.
VOID FASTCALL	PhfWaitForCondition (_Inout_ PPH_QUEUED_LOCK Condition, _Inout_ PPH_QUEUED_LOCK Lock, _In_opt_ PLARGE_INTEGER Timeout)
	Sleeps on a condition variable.
VOID FASTCALL	PhfWaitForConditionEx (_Inout_ PPH_QUEUED_LOCK Condition, _Inout_ PVOID Lock, _In_ ULONG Flags, _In_opt_ PLARGE_INTEGER Timeout)
	Sleeps on a condition variable.
VOID FASTCALL	PhfQueueWakeEvent (_Inout_ PPH_QUEUED_LOCK WakeEvent, _Out_ PPH_QUEUED_WAIT_BLOCK WaitBlock)
	Queues a wait block to a wake event.
VOID FASTCALL	PhfSetWakeEvent (_Inout_ PPH_QUEUED_LOCK WakeEvent, _Inout_opt_ PPH_QUEUED_WAIT_BLOCK WaitBlock)
	Sets a wake event, unblocking all queued wait blocks.
NTSTATUS FASTCALL	PhfWaitForWakeEvent (_Inout_ PPH_QUEUED_LOCK WakeEvent, _Inout_ PPH_QUEUED_WAIT_BLOCK WaitBlock, _In_ BOOLEAN Spin, _In_opt_ PLARGE_INTEGER Timeout)
	Waits for a wake event to be set.

Function Documentation

VOID FASTCALL PhfAcquireQueuedLockExclusive

(

_Inout_ PPH_QUEUED_LOCK

QueuedLock

)

Acquires a queued lock in exclusive mode.

Parameters

QueuedLock

A queued lock.

Definition at line 678 of file queuedlock.c.

VOID FASTCALL PhfAcquireQueuedLockShared

(

_Inout_ PPH_QUEUED_LOCK

QueuedLock

)

Acquires a queued lock in shared mode.

Parameters

QueuedLock

A queued lock.

Definition at line 730 of file queuedlock.c.

VOID FASTCALL PhfPulseAllCondition

(

_Inout_ PPH_QUEUED_LOCK

Condition

)

Wakes all threads sleeping on a condition variable.

Parameters

Condition

A condition variable.

Remarks

The associated lock must be acquired before calling the function.

Definition at line 1017 of file queuedlock.c.

VOID FASTCALL PhfPulseCondition

(

_Inout_ PPH_QUEUED_LOCK

Condition

)

Wakes one thread sleeping on a condition variable.

Parameters

Condition

A condition variable.

Remarks

The associated lock must be acquired before calling the function.

Definition at line 1001 of file queuedlock.c.

VOID FASTCALL PhfQueueWakeEvent	(	_Inout_ PPH_QUEUED_LOCK	WakeEvent,
		_Out_ PPH_QUEUED_WAIT_BLOCK	WaitBlock
	)

Queues a wait block to a wake event.

Parameters

WakeEvent	A wake event.
WaitBlock	A wait block.

Remarks

If you later determine that the wait should not occur, you must call PhfSetWakeEvent() to dequeue the wait block.

Definition at line 1179 of file queuedlock.c.

VOID FASTCALL PhfReleaseQueuedLockExclusive

(

_Inout_ PPH_QUEUED_LOCK

QueuedLock

)

Releases a queued lock in exclusive mode.

Parameters

QueuedLock

A queued lock.

Definition at line 792 of file queuedlock.c.

VOID FASTCALL PhfReleaseQueuedLockShared

(

_Inout_ PPH_QUEUED_LOCK

QueuedLock

)

Releases a queued lock in shared mode.

Parameters

QueuedLock

A queued lock.

Definition at line 852 of file queuedlock.c.

VOID FASTCALL PhfSetWakeEvent	(	_Inout_ PPH_QUEUED_LOCK	WakeEvent,
		_Inout_opt_ PPH_QUEUED_WAIT_BLOCK	WaitBlock
	)

Sets a wake event, unblocking all queued wait blocks.

Parameters

WakeEvent	A wake event.
WaitBlock	A wait block for a cancelled wait, otherwise NULL.

Definition at line 1213 of file queuedlock.c.

VOID FASTCALL PhfTryWakeQueuedLock

(

_Inout_ PPH_QUEUED_LOCK

QueuedLock

)

Wakes waiters in a queued lock, making no assumptions about the state of the lock.

Parameters

QueuedLock

A queued lock.

Remarks

This function exists only for compatibility reasons.

Definition at line 935 of file queuedlock.c.

VOID FASTCALL PhfWaitForCondition	(	_Inout_ PPH_QUEUED_LOCK	Condition,
		_Inout_ PPH_QUEUED_LOCK	Lock,
		_In_opt_ PLARGE_INTEGER	Timeout
	)

Sleeps on a condition variable.

Parameters

Condition	A condition variable.
Lock	A queued lock to release/acquire in exclusive mode.
Timeout	Not implemented.

Remarks

The associated lock must be acquired before calling the function.

Definition at line 1035 of file queuedlock.c.

VOID FASTCALL PhfWaitForConditionEx	(	_Inout_ PPH_QUEUED_LOCK	Condition,
		_Inout_ PVOID	Lock,
		_In_ ULONG	Flags,
		_In_opt_ PLARGE_INTEGER	Timeout
	)

Sleeps on a condition variable.

Parameters

Condition	A condition variable.
Lock	A pointer to a lock.
Flags	A combination of flags controlling the operation.
Timeout	Not implemented.

Definition at line 1086 of file queuedlock.c.

NTSTATUS FASTCALL PhfWaitForWakeEvent	(	_Inout_ PPH_QUEUED_LOCK	WakeEvent,
		_Inout_ PPH_QUEUED_WAIT_BLOCK	WaitBlock,
		_In_ BOOLEAN	Spin,
		_In_opt_ PLARGE_INTEGER	Timeout
	)

Waits for a wake event to be set.

Parameters

WakeEvent	A wake event.
WaitBlock	A wait block previously queued to the wake event using PhfQueueWakeEvent().
Spin	TRUE to spin on the wake event before blocking, FALSE to block immediately.
Timeout	A timeout value.

Remarks

Wake events are subject to spurious wakeups. You should call this function in a loop which checks a predicate.

Definition at line 1274 of file queuedlock.c.

VOID FASTCALL PhfWakeForReleaseQueuedLock	(	_Inout_ PPH_QUEUED_LOCK	QueuedLock,
		_In_ ULONG_PTR	Value
	)

Wakes waiters in a queued lock for releasing it in exclusive mode.

Parameters

QueuedLock	A queued lock.
Value	The current value of the queued lock.

Remarks

The function assumes the following flags are set: PH_QUEUED_LOCK_WAITERS. The function assumes the following flags are not set: PH_QUEUED_LOCK_MULTIPLE_SHARED, PH_QUEUED_LOCK_TRAVERSING.

Definition at line 974 of file queuedlock.c.

_May_raise_ FORCEINLINE NTSTATUS PhpBlockOnQueuedWaitBlock	(	_Inout_ PPH_QUEUED_WAIT_BLOCK	WaitBlock,
		_In_ BOOLEAN	Spin,
		_In_opt_ PLARGE_INTEGER	Timeout
	)

Waits for a wait block to be unblocked.

Parameters

WaitBlock	A wait block.
Spin	TRUE to spin, FALSE to block immediately.
Timeout	A timeout value.

Definition at line 298 of file queuedlock.c.

FORCEINLINE PPH_QUEUED_WAIT_BLOCK PhpFindLastQueuedWaitBlock

(

_In_ ULONG_PTR

Value

)

Finds the last wait block in the waiters list.

Parameters

Value

The current value of the queued lock.

Returns

A pointer to the last wait block.

Remarks

The function assumes the following flags are set: PH_QUEUED_LOCK_WAITERS, PH_QUEUED_LOCK_MULTIPLE_SHARED or PH_QUEUED_LOCK_TRAVERSING.

Definition at line 258 of file queuedlock.c.

VOID FASTCALL PhpfOptimizeQueuedLockList	(	_Inout_ PPH_QUEUED_LOCK	QueuedLock,
		_In_ ULONG_PTR	Value
	)

Optimizes a queued lock waiters list.

Parameters

QueuedLock	A queued lock.
Value	The current value of the queued lock.

Remarks

The function assumes the following flags are set: PH_QUEUED_LOCK_WAITERS, PH_QUEUED_LOCK_TRAVERSING.

Definition at line 463 of file queuedlock.c.

VOID FASTCALL PhpfWakeQueuedLock	(	_Inout_ PPH_QUEUED_LOCK	QueuedLock,
		_In_ ULONG_PTR	Value
	)

Wakes waiters in a queued lock.

Parameters

QueuedLock	A queued lock.
Value	The current value of the queued lock.

Remarks

The function assumes the following flags are set: PH_QUEUED_LOCK_WAITERS, PH_QUEUED_LOCK_TRAVERSING. The function assumes the following flags are not set: PH_QUEUED_LOCK_MULTIPLE_SHARED.

Definition at line 616 of file queuedlock.c.

VOID FASTCALL PhpfWakeQueuedLockEx	(	_Inout_ PPH_QUEUED_LOCK	QueuedLock,
		_In_ ULONG_PTR	Value,
		_In_ BOOLEAN	IgnoreOwned,
		_In_ BOOLEAN	WakeAll
	)

Wakes waiters in a queued lock.

Parameters

QueuedLock	A queued lock.
Value	The current value of the queued lock.
IgnoreOwned	TRUE to ignore lock state, FALSE to conduct normal checks.
WakeAll	TRUE to wake all waiters, FALSE to decide based on the wait block type.

Remarks

The function assumes the following flags are set: PH_QUEUED_LOCK_WAITERS, PH_QUEUED_LOCK_TRAVERSING. The function assumes the following flags are not set: PH_QUEUED_LOCK_MULTIPLE_SHARED.

Definition at line 651 of file queuedlock.c.

FORCEINLINE VOID PhpOptimizeQueuedLockListEx	(	_Inout_ PPH_QUEUED_LOCK	QueuedLock,
		_In_ ULONG_PTR	Value,
		_In_ BOOLEAN	IgnoreOwned
	)

Optimizes a queued lock waiters list.

Parameters

QueuedLock	A queued lock.
Value	The current value of the queued lock.
IgnoreOwned	TRUE to ignore lock state, FALSE to conduct normal checks.

Remarks

The function assumes the following flags are set: PH_QUEUED_LOCK_WAITERS, PH_QUEUED_LOCK_TRAVERSING.

Definition at line 382 of file queuedlock.c.

FORCEINLINE PPH_QUEUED_WAIT_BLOCK PhpPrepareToWakeQueuedLock	(	_Inout_ PPH_QUEUED_LOCK	QueuedLock,
		_In_ ULONG_PTR	Value,
		_In_ BOOLEAN	IgnoreOwned,
		_In_ BOOLEAN	WakeAll
	)

Dequeues the appropriate number of wait blocks in a queued lock.

Parameters

QueuedLock	A queued lock.
Value	The current value of the queued lock.
IgnoreOwned	TRUE to ignore lock state, FALSE to conduct normal checks.
WakeAll	TRUE to remove all wait blocks, FALSE to decide based on the wait block type.

Definition at line 482 of file queuedlock.c.

FORCEINLINE BOOLEAN PhpPushQueuedWaitBlock	(	_Inout_ PPH_QUEUED_LOCK	QueuedLock,
		_In_ ULONG_PTR	Value,
		_In_ BOOLEAN	Exclusive,
		_Out_ PPH_QUEUED_WAIT_BLOCK	WaitBlock,
		_Out_ PBOOLEAN	Optimize,
		_Out_ PULONG_PTR	NewValue,
		_Out_ PULONG_PTR	CurrentValue
	)

Pushes a wait block onto a queued lock's waiters list.

Parameters

QueuedLock	A queued lock.
Value	The current value of the queued lock.
Exclusive	Whether the wait block is in exclusive mode.
WaitBlock	A variable which receives the resulting wait block structure.
Optimize	A variable which receives a boolean indicating whether to optimize the waiters list.
NewValue	The old value of the queued lock. This value is useful only if the function returns FALSE.
CurrentValue	The new value of the queued lock. This value is useful only if the function returns TRUE.

Returns

TRUE if the wait block was pushed onto the waiters list, otherwise FALSE.

Remarks

• The function assumes the following flags are set: PH_QUEUED_LOCK_OWNED.
• Do not move the wait block location after this function is called.
• The Optimize boolean is a hint to call PhpfOptimizeQueuedLockList() if the function succeeds. It is recommended, but not essential that this occurs.
• Call PhpBlockOnQueuedWaitBlock() to wait for the wait block to be unblocked.

Definition at line 160 of file queuedlock.c.

_May_raise_ FORCEINLINE VOID PhpUnblockQueuedWaitBlock

(

_Inout_ PPH_QUEUED_WAIT_BLOCK

WaitBlock

)

Unblocks a wait block.

Parameters

WaitBlock

A wait block.

Remarks

The wait block is in an undefined state after it is unblocked. Do not attempt to read any values from it. All relevant information should be saved before unblocking the wait block.

Definition at line 353 of file queuedlock.c.

BOOLEAN PhQueuedLockInitialization

(

VOID

)

Definition at line 110 of file queuedlock.c.