NdisInitializeReadWriteLock function (ndis.h)

Article
10/21/2021

The NdisInitializeReadWriteLock function initializes a read or write lock variable of type NDIS_RW_LOCK.

Note The read-write lock interface is deprecated for NDIS 6.20 and later drivers, which should use NdisAllocateRWLock instead of NdisInitializeReadWriteLock.

Syntax

void NdisInitializeReadWriteLock(
  [out] PNDIS_RW_LOCK Lock
);

Parameters

[out] Lock

A pointer to an opaque NDIS_RW_LOCK variable that represents a lock. The caller can use this lock to gain write or read access to resources that are shared among non-ISR driver threads.

Return value

None

Remarks

An NDIS_RW_LOCK variable is used to limit write access to shared resources to one non-ISR driver thread at a time. This NDIS_RW_LOCK can allow multiple non-ISR driver threads concurrent read access to those resources. Such read access is not permitted during a write access.

The Lock pointer that is passed to NdisInitializeReadWriteLock is a required parameter for all other Ndis..ReadWriteLock functions.

Before a driver calls the NdisAcquireReadWriteLock function to obtain write or read access to a resource, the driver must call NdisInitializeReadWriteLock to initialize the lock that is associated with that resource. The caller must provide nonpaged storage for the variable at Lock .

After calling NdisInitializeReadWriteLock, the driver can call NdisAcquireReadWriteLock to obtain either write or read access to the resource. Only one non-ISR driver thread at a time can obtain write access to the resource. When one non-ISR thread has write access, all read and write accesses by other non-ISR threads must wait until the write-access holder releases the lock. However, if a non-ISR thread has read access, other non-ISR threads can concurrently acquire read access.

Initialize and use this type of lock for resources that are frequently accessed for reading and infrequently accessed for writing.

Once resource access is complete, the driver calls the NdisReleaseReadWriteLock function.

Each lock that a driver initializes does one of the following:

Protects a discrete set of shared resources from simultaneous write and read access by driver threads that run at IRQL <= DISPATCH_LEVEL.
Exposes a discrete set of shared resources to simultaneous read access by driver threads that run at IRQL <= DISPATCH_LEVEL.

Callers of NdisInitializeReadWriteLock can run at any IRQL. Usually a caller is running at IRQL = PASSIVE_LEVEL during initialization.

Requirements

Requirement	Value
Minimum supported client	Deprecated for NDIS 6.20 and later drivers, which should use NdisAllocateRWLock instead of NdisInitializeReadWriteLock. Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisInitializeReadWriteLock (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisInitializeReadWriteLock (NDIS 5.1)) in Windows XP.
Target Platform	Universal
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
DLL	Ndis.sys
IRQL	Any level (see Remarks section)