ExQueueWorkItem - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
// wdm.h

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

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Windows Driver Kit DDI reference (nf-wdm-exqueueworkitem)

Description

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.

Parameters

WorkItem [in, out]

Pointer to the work item. This work item must have been initialized by a preceding call to ExInitializeWorkItem.

QueueType [in]

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.

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:

Threads at either priority remain interruptible.

See also

ExFreePool

ExFreePoolWithTag

ExInitializeWorkItem

IoAllocateWorkItem

IoFreeWorkItem

IoQueueWorkItem

WORK_QUEUE_ITEM