Функция NdisAllocateRWLock (ndis.h)

Статья
08/07/2023

Функция NdisAllocateRWLock выделяет переменную блокировки чтения и записи типа NDIS_RW_LOCK_EX.

Синтаксис

PNDIS_RW_LOCK_EX NdisAllocateRWLock(
  NDIS_HANDLE NdisHandle
);

Параметры

NdisHandle

Дескриптор, возвращаемый одной из следующих функций:

NdisMRegisterMiniportDriver
MiniportInitializeEx
NdisRegisterProtocolDriver
NdisOpenAdapterEx
NdisFRegisterFilterDriver
FilterAttach
Windows 8 и Windows Server 2012 и более поздних версий. Если блокировка чтения и записи выделяется в DriverEntry до того, как будет доступен какой-либо дескриптор NDIS, вызывающий объект может передать значение NULL для этого параметра.

Возвращаемое значение

NdisAllocateRWLock возвращает указатель на структуру NDIS_RW_LOCK_EX , если ее можно выделить; в противном случае возвращается ЗНАЧЕНИЕ NULL.

Драйверы NDIS вызывают функцию NdisAllocateRWLock для выделения структуры NDIS_RW_LOCK_EX , которая управляет доступом на чтение и запись к ресурсам, которые совместно используются потоками драйверов. Драйверы используют блокировку для чтения и записи для ресурсов, к которым часто обращаются для чтения и редко используются для записи.

Каждая блокировка, выделенная драйвером, может выполнять одно из следующих действий.

Защитите дискретный набор общих ресурсов от параллельного доступа на запись и чтение потоками драйверов, которые выполняются в IRQL <= DISPATCH_LEVEL.
Предоставление дискретного набора общих ресурсов для параллельного доступа на чтение потоками драйверов, которые выполняются в IRQL <= DISPATCH_LEVEL.

Указатель NDIS_RW_LOCK_EX , возвращаемый NdisAllocateRWLock , является обязательным параметром для всех остальных функций блокировки чтения и записи.

NDIS_RW_LOCK_EX не является справедливым. То есть процессор, ожидающий получения блокировки для монопольного доступа, может быть голоден процессорами, которые удерживают блокировку для доступа на чтение. Поэтому не используйте NDIS_RW_LOCK_EX в ситуациях, когда большинство обращений будет использоваться для доступа на запись. Если большинству обращений требуется доступ на запись, эффективнее использовать блокировку спина ядра. Дополнительные сведения о спиновых блокировках см. в статье Введение в спиновые блокировки.

В ситуациях, когда существует много приобретений для доступа на чтение на нескольких процессорах, NDIS_RW_LOCK_EX обычно работает лучше, чем блокировка спина ядра. Используйте NDIS_RW_LOCK_EX , если ожидается большое количество операций чтения в секунду, распределенных между несколькими процессорами.

Структура NDIS_RW_LOCK_EX определяет атрибуты, которые ограничивают доступ на запись к общим ресурсам одним потоком драйвера, не относящееся к ISR, за раз. Структура NDIS_RW_LOCK_EX позволяет нескольким потокам драйверов, не связанным с ISR, иметь параллельный доступ на чтение связанных ресурсов. Такой доступ на чтение не разрешен во время доступа на запись.

Чтобы изменить защищенные ресурсы, поток драйвера должен получить блокировку записи с помощью функции NdisAcquireRWLockWrite . Чтобы просто считывать эти ресурсы, поток драйвера должен получить блокировку только для чтения с помощью функции NdisAcquireRWLockRead . Доступ на чтение не требует взаимосвязанных операций или конфликтов для спиновых блокировок. Доступ только для чтения помогает поддерживать высокую производительность операционной системы и драйвера.

После завершения доступа к ресурсу драйвер вызывает функцию NdisReleaseRWLock .

Драйвер должен вызвать функцию NdisFreeRWLock , чтобы освободить структуру NDIS_RW_LOCK_EX , выделенную с помощью функции NdisAllocateRWLock .

С помощью расширения отладчика !ndiskd.ndisrwlock можно проверить NDIS_RW_LOCK_EX, узнать, сколько у него читателей, а также узнать, кто является его текущим модулем записи. Дополнительные сведения см. в разделе Расширения NDIS (Ndiskd.dll).

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.20 и более поздних версиях.
Целевая платформа	Универсальное
Верхняя часть	ndis.h (включая Ndis.h)
Библиотека	Ndis.lib
IRQL	<=DISPATCH_LEVEL