Função ExQueueWorkItem (wdm.h)

Artigo
03/08/2023

ExQueueWorkItem insere um determinado item de trabalho em uma fila da qual um thread de trabalho do sistema remove o item e dá controle à rotina que o chamador forneceu ao ExInitializeWorkItem.

Aviso

Use essa rotina com extrema cautela. Consulte a seção Comentários abaixo.

Sintaxe

void ExQueueWorkItem(
  [in, out] __drv_aliasesMem PWORK_QUEUE_ITEM WorkItem,
  [in]      WORK_QUEUE_TYPE                   QueueType
);

Parâmetros

[in, out] WorkItem

Ponteiro para o item de trabalho. Este item de trabalho deve ter sido inicializado por uma chamada anterior para ExInitializeWorkItem.

[in] QueueType

Especifica a fila na qual o item de trabalho apontado por WorkItem deve ser inserido. QueueType pode ser um dos seguintes:

Valor	Significado
CriticalWorkQueue	Insira o WorkItem na fila da qual um thread do sistema com um atributo de prioridade em tempo real processará o item de trabalho.
DelayedWorkQueue	Insira o WorkItem na fila da qual um thread do sistema com um atributo de prioridade variável processará o item de trabalho.

O valor QueueType HyperCriticalWorkQueue é reservado para uso do sistema.

Retornar valor

Nenhum

Comentários

Os drivers de dispositivo devem usar IoQueueWorkItem em vez de ExQueueWorkItem. Os drivers devem usar ExQueueWorkItem e o ExInitializeWorkItem associado, somente nos casos em que o item de trabalho especificado não está associado a um objeto de dispositivo ou pilha de dispositivos. Em todos os outros casos, os drivers devem usar IoAllocateWorkItem, IoFreeWorkItem e IoQueueWorkItem porque apenas essas rotinas garantem que o objeto do dispositivo associado ao item de trabalho especificado permaneça disponível até que o item de trabalho seja processado.

A rotina de retorno de chamada especificada no parâmetro Routine para ExInitializeWorkItem é chamada em um contexto de sistema no PASSIVE_LEVEL IRQL. Essa rotina fornecida pelo chamador é responsável por liberar o item de trabalho quando ele não é mais necessário chamando ExFreePool ou ExFreePoolWithTag.

Os threads de trabalho do sistema são um recurso limitado. Os drivers não devem reservar permanentemente um item de trabalho para uso do driver. Os itens de trabalho são projetados para operações que são concluídas rapidamente. Os drivers devem liberar todos os itens de trabalho alocados assim que possível.

Um driver não deve esperar que sua rotina de retorno de chamada conclua uma operação se já estiver mantendo um objeto de sincronização e puder tentar adquirir outro. Para evitar deadlock, um driver deve liberar semáforos, mutexes, variáveis de recurso atualmente mantidos e assim por diante antes de chamar ExQueueWorkItem.

O valor de QueueType determina a prioridade de runtime na qual a rotina de retorno de chamada é executada, da seguinte maneira:

Se o retorno de chamada for executado no thread do sistema com um atributo de prioridade em tempo real, a rotina de retorno de chamada não poderá ser preempcionada, exceto por threads com prioridades mais altas em tempo real.
Se o retorno de chamada for executado no thread do sistema com um atributo de prioridade variável, o retorno de chamada poderá ser precedido por threads com prioridades mais altas de variável e em tempo real, e o retorno de chamada será agendado para executar round robin com outros threads da mesma prioridade para um quantum cada um.

Os threads em qualquer prioridade permanecem interrompíveis.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntifs.h, Fltkernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL