ExQueueWorkItem, fonction (wdm.h)

Article
02/27/2024

ExQueueWorkItem insère un élément de travail donné dans une file d’attente à partir de laquelle un thread de travail système supprime l’élément et donne le contrôle à la routine que l’appelant a fournie à ExInitializeWorkItem.

Avertissement

Utilisez cette routine avec une extrême prudence. Consultez la section Notes ci-dessous.

Syntaxe

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

Paramètres

[in, out] WorkItem

Pointeur vers l’élément de travail. Cet élément de travail doit avoir été initialisé par un appel précédent à ExInitializeWorkItem.

[in] QueueType

Spécifie la file d’attente dans laquelle l’élément de travail pointé par WorkItem doit être inséré. QueueType peut être l’un des éléments suivants :

Valeur	Signification
CriticalWorkQueue	Insérez l’objet WorkItem dans la file d’attente à partir de laquelle un thread système avec un attribut de priorité en temps réel traitera l’élément de travail.
DelayedWorkQueue	Insérez l’objet WorkItem dans la file d’attente à partir de laquelle un thread système avec un attribut de priorité variable traitera l’élément de travail.

La valeur QueueTypeHyperCriticalWorkQueue est réservée à l’utilisation système.

Valeur de retour

None

Remarques

Les pilotes de périphérique doivent utiliser IoQueueWorkItem au lieu d’ExQueueWorkItem. Les pilotes doivent utiliser ExQueueWorkItem et l’objet ExInitializeWorkItem associé, uniquement dans les cas où l’élément de travail spécifié n’est pas associé à un objet de périphérique ou à une pile de périphériques. Dans tous les autres cas, les pilotes doivent utiliser IoAllocateWorkItem, IoFreeWorkItem et IoQueueWorkItem , car seules ces routines garantissent que l’objet d’appareil associé à l’élément de travail spécifié reste disponible jusqu’à ce que l’élément de travail ait été traité.

La routine de rappel spécifiée dans le paramètre Routine sur ExInitializeWorkItem est appelée dans un contexte système au PASSIVE_LEVEL IRQL. Cette routine fournie par l’appelant est chargée de libérer l’élément de travail lorsqu’il n’est plus nécessaire en appelant ExFreePool ou ExFreePoolWithTag.

Les threads de travail système sont une ressource limitée. Les conducteurs ne doivent pas réserver de façon permanente un élément de travail à l’usage du conducteur. Les éléments de travail sont conçus pour les opérations qui se terminent rapidement. Les pilotes doivent libérer tous les éléments de travail qu’ils allouent dès que possible.

Un pilote ne doit pas attendre que sa routine de rappel termine une opération s’il contient déjà un objet de synchronisation et peut tenter d’en acquérir un autre. Pour éviter l’interblocage, un pilote doit libérer les sémaphores, mutex, variables de ressources, etc. avant d’appeler ExQueueWorkItem.

La valeur de QueueType détermine la priorité d’exécution à laquelle la routine de rappel est exécutée, comme suit :

Si le rappel s’exécute dans le thread système avec un attribut de priorité en temps réel, la routine de rappel ne peut pas être préemptée, sauf par des threads avec des priorités en temps réel plus élevées.
Si le rappel s’exécute dans le thread système avec un attribut de priorité variable, le rappel peut être préempté par des threads ayant des priorités de variables et en temps réel plus élevées, et le rappel est planifié pour exécuter le tourniquet (round robin) avec d’autres threads de la même priorité pour un quantum chacun.

Les threads de l’une ou l’autre priorité restent interruptibles.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntifs.h, Fltkernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL