ExQueueWorkItem function (wdm.h)
ExQueueWorkItem inserts a given work item into a queue from which a system worker thread removes the item and gives control to the routine that the caller supplied to ExInitializeWorkItem.
Warning
Use this routine with extreme caution. See the Remarks section below.
Syntax
void ExQueueWorkItem(
[in, out] __drv_aliasesMem PWORK_QUEUE_ITEM WorkItem,
[in] WORK_QUEUE_TYPE QueueType
);
Parameters
[in, out] WorkItem
Pointer to the work item. This work item must have been initialized by a preceding call to ExInitializeWorkItem.
[in] QueueType
Specifies the queue into which the work item pointed to by WorkItem is to be inserted. QueueType can be either of the following:
| Value | Meaning |
|---|---|
| CriticalWorkQueue | Insert the WorkItem into the queue from which a system thread with a real-time priority attribute will process the work item. |
| DelayedWorkQueue | Insert the WorkItem into the queue from which a system thread with a variable priority attribute will process the work item. |
The QueueType value HyperCriticalWorkQueue is reserved for system use.
Return value
None
Remarks
Device drivers must use IoQueueWorkItem instead of ExQueueWorkItem. Drivers should use ExQueueWorkItem, and the associated ExInitializeWorkItem, only in cases where the specified work item is not associated with a device object or device stack. In all other cases, drivers should use IoAllocateWorkItem, IoFreeWorkItem, and IoQueueWorkItem because only these routines ensure that the device object associated with the specified work item remains available until the work item has been processed.
The callback routine that was specified in the Routine parameter to ExInitializeWorkItem is called in a system context at IRQL PASSIVE_LEVEL. This caller-supplied routine is responsible for freeing the work item when it is no longer needed by calling ExFreePool or ExFreePoolWithTag.
System worker threads are a limited resource. Drivers must not permanently reserve a work item for the driver's use. Work items are designed for operations that complete quickly. Drivers should free any work items that they allocate as soon as possible.
A driver must not wait for its callback routine to complete an operation if it is already holding one synchronization object and might attempt to acquire another. To prevent deadlock, a driver should release any currently held semaphores, mutexes, resource variables, and so forth before it calls ExQueueWorkItem.
The value of QueueType determines the runtime priority at which the callback routine is run, as follows:
If the callback runs in the system thread with a real-time priority attribute, the callback routine cannot be preempted except by threads with higher real-time priorities.
If the callback runs in the system thread with a variable priority attribute, the callback can be preempted by threads with higher variable and real-time priorities, and the callback is scheduled to run round-robin with other threads of the same priority for a quantum each.
Threads at either priority remain interruptible.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | wdm.h (include Wdm.h, Ntifs.h, Fltkernel.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL |