Função NdisAllocateRWLock (ndis.h)

Artigo
03/01/2024

A função NdisAllocateRWLock aloca uma variável de bloqueio de leitura/gravação do tipo NDIS_RW_LOCK_EX.

Sintaxe

PNDIS_RW_LOCK_EX NdisAllocateRWLock(
  NDIS_HANDLE NdisHandle
);

Parâmetros

NdisHandle

Um identificador retornado de uma das seguintes funções:

NdisMRegisterMiniportDriver
MiniportInitializeEx
NdisRegisterProtocolDriver
NdisOpenAdapterEx
NdisFRegisterFilterDriver
FilterAttach
Windows 8 e Windows Server 2012 e posteriores: se o bloqueio de leitura/gravação estiver sendo alocado em DriverEntry antes que qualquer identificador NDIS esteja disponível, o chamador poderá passar um valor NULL para esse parâmetro.

Retornar valor

NdisAllocateRWLock retornará um ponteiro para uma estrutura NDIS_RW_LOCK_EX se for possível alocar; caso contrário, retornará NULL.

Comentários

Os drivers NDIS chamam a função NdisAllocateRWLock para alocar uma estrutura NDIS_RW_LOCK_EX que controla o acesso de leitura/gravação a recursos compartilhados entre threads de driver. Os drivers usam um bloqueio de leitura/gravação para recursos acessados com frequência para leitura e acessados com pouca frequência para gravação.

Cada bloqueio alocado por um driver pode fazer um dos seguintes procedimentos:

Proteja um conjunto discreto de recursos compartilhados contra acesso simultâneo de gravação e leitura por threads de driver executados em IRQL <= DISPATCH_LEVEL.
Exponha um conjunto discreto de recursos compartilhados para acesso de leitura simultâneo por threads de driver executados em IRQL <= DISPATCH_LEVEL.

O ponteiro NDIS_RW_LOCK_EX que NdisAllocateRWLock retorna é um parâmetro necessário para todas as outras funções de bloqueio de leitura/gravação.

Um NDIS_RW_LOCK_EX não é justo. Ou seja, um processador que aguarda a aquisição do bloqueio para acesso exclusivo pode ficar sem processadores que mantêm o bloqueio para acesso de leitura. Portanto, não use uma NDIS_RW_LOCK_EX em situações em que a maioria dos acessos será para acesso de gravação. Se a maioria dos acessos precisar de acesso de gravação, é mais eficiente simplesmente usar um bloqueio de rotação do kernel. Para obter mais informações sobre bloqueios de rotação, consulte Introdução aos bloqueios de rotação.

Em situações em que há muitas aquisições para acesso de leitura em mais de um processador, o NDIS_RW_LOCK_EX normalmente tem um desempenho melhor do que um bloqueio de rotação de kernel. Use NDIS_RW_LOCK_EX quando você espera muitos acessos de leitura por segundo distribuídos em mais de um processador.

Uma estrutura NDIS_RW_LOCK_EX define atributos que limitam o acesso de gravação a recursos compartilhados a um thread de driver não ISR por vez. A estrutura NDIS_RW_LOCK_EX pode permitir que vários threads de driver não ISR tenham acesso de leitura simultâneo aos recursos associados. Esse acesso de leitura não é permitido durante um acesso de gravação.

Para modificar os recursos protegidos, um thread de driver deve obter um bloqueio de gravação com a função NdisAcquireRWLockWrite . Para simplesmente ler esses recursos, um thread de driver deve obter um bloqueio somente leitura com a função NdisAcquireRWLockRead . O acesso de leitura não requer operações interligadas nem contenção para bloqueios de rotação. O acesso somente leitura ajuda a manter um bom desempenho do sistema operacional e do driver.

Depois que o acesso ao recurso for concluído, o driver chamará a função NdisReleaseRWLock .

Um driver deve chamar a função NdisFreeRWLock para liberar a estrutura NDIS_RW_LOCK_EX alocada com a função NdisAllocateRWLock .

Você pode usar a extensão de depurador !ndiskd.ndisrwlock para inspecionar um NDIS_RW_LOCK_EX, ver quantos leitores ele tem e ver quem é seu gravador atual. Para obter mais informações, consulte Extensões do NDIS (Ndiskd.dll).

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte no NDIS 6.20 e posterior.
Plataforma de Destino	Universal
Cabeçalho	ndis.h (inclua Ndis.h)
Biblioteca	Ndis.lib
IRQL	<=DISPATCH_LEVEL