FltInitializePushLock function (fltkernel.h)

Article
11/30/2021

The FltInitializePushLock routine initializes a push lock variable.

Syntax

VOID FLTAPI FltInitializePushLock(
  [out] PEX_PUSH_LOCK PushLock
);

Parameters

[out] PushLock

Pointer to the caller-supplied storage, which must be at least the value of sizeof(EX_PUSH_LOCK), for the push lock variable to be initialized. The storage must be 4-byte aligned on 32-bit platforms, and 8-byte aligned on 64-bit platforms.

Return value

None

Remarks

Push locks are rarely a good choice for file system minifilters. As described below, some of their characteristics can be incompatible with the inherently re-entrant nature of file systems.

Push locks are similar to ERESOURCE structures (also called "resources") in the following ways:

Push locks can be used for synchronization by a set of threads.
Push locks can be acquired for shared or exclusive access.
Although the caller provides the storage for the push lock variable, the EX_PUSH_LOCK structure is opaque: that is, its members are reserved for system use.

Push locks have the following disadvantages when compared with ERESOURCE structures:

The algorithm for granting exclusive access is not fair to all threads. If there is a high level of exclusive-lock contention, there is no guarantee about the order in which threads will be granted exclusive access.
There are no support routines for determining the current owner of a push lock at run time. (Users of ERESOURCE structures can call routines such as ExIsResourceAcquiredExclusiveLite to determine whether the current thread has exclusive access to the resource.)
For the same reason there are no support extensions for determining the current owner of a push lock at debug time, and thus diagnosing deadlocks. (Users of ERESOURCE structures can use the !locks extension in kd or windbg to find this out.)
There is no driver verifier support to help early diagnosis of deadlocks through push locks.
Exclusive push locks cannot be acquired recursively.

Push locks offer the following advantages over ERESOURCE structures:

When push locks are mostly acquired for shared access, they are more efficient than ERESOURCE structures.
The storage for push locks can be allocated from paged or nonpaged pool. ERESOURCE structures must be allocated only from nonpaged pool.
EX_PUSH_LOCK structures are much smaller than ERESOURCE structures.

Unless any of these advantages are compelling an ERESOURCE is usually the more robust and maintainable solution to the Read/Write synchronization problem.

To acquire a push lock for exclusive access, call FltAcquirePushLockExclusive.

To acquire a push lock for shared access, call FltAcquirePushLockShared.

To release a push lock, call FltReleasePushLock.

To delete a push lock, call FltDeletePushLock.

Requirements

Requirement	Value
Minimum supported client	This routine is available on Microsoft Windows XP SP2, Microsoft Windows Server 2003 SP1, and later.
Target Platform	Universal
Header	fltkernel.h (include Fltkernel.h)
Library	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL