IoTryQueueWorkItem routine

Article
12/21/2017

The IoTryQueueWorkItem routine queues a work item to a worker thread, when available, for a specified queue type.

Syntax

BOOLEAN IoTryQueueWorkItem(
  _In_     PIO_WORKITEM            IoWorkItem,
  _In_     PIO_WORKITEM_ROUTINE_EX WorkerRoutine,
  _In_     WORK_QUEUE_TYPE         QueueType,
  _In_opt_ PVOID                   Context
);

Parameters

IoWorkItem [in]
A pointer to a work item to add to the work item queue. This must point to a work item previously allocated by IoAllocateWorkItem or initialized by IoInitializeWorkItem.
WorkerRoutine [in]
A pointer to a driver supplied worker routine, WorkItemEx, that will process the work item. This routine is called within the context of a system thread.
QueueType [in]
Specifies the queue into which the work item pointed to by WorkItem is inserted. QueueType is one of the priority queue type values in the WORK_QUEUE_TYPE enumeration.
Context [in, optional]
A pointer to an optional context that is supplied to the worker routine pointed to by WorkerRoutine. This specifies driver-specific information for the work item. The system passes this value as the Context parameter to WorkItemEx.

Return value

Returns TRUE if the work item was successfully inserted into a system worker thread queue. Otherwise, returns FALSE.

Remarks

The IoTryQueueWorkItem routine attempts to assign a work item directly to an available thread for the selected queue type. It tries to find available threads for each node in the system, starting with the current node. If no threads are available for any node, FALSE is returned. IoTryQueueWorkItem returns TRUE only when the work item is queued. This happens only if the system can guarantee that the work item can begin execution with the resources and threads that are currently allocated.

IoTryQueueWorkItem is intended for use by file system drivers and file system filter drivers to handle page writes. The routine will guarantee a forward progress path for page free requests.

Drivers using IoTryQueueWorkItem must handle the failure case when FALSE is returned. If IoTryQueueWorkItem cannot queue the work item, a driver could execute the work item directly if possible, or use a previously created dedicated system thread, known as an emergency thread, to process the work item. When implementing a fallback handler for work items that failed to queue, a driver should use a simple mechanism with a minimum of resources necessary to achieve forward progress (e.g, a simple private work queue and a work item list). It is not necessary to create a fallback handler that provides for a high degree parallelism and scalability. IoTryQueueWorkItem will succeed whenever possible and is designed to handle work distribution and parallelism efficiently. It is not necessary to duplicate this functionality in a driver.

Note This routine is available starting with Windows 8 but is not declared in the Windows Driver Kit (WDK) until Windows Driver Kit (WDK) 8.1 Update.

Requirements

Target platform	Universal
Version	Available starting with Windows 8.
Header	Wdm.h (include Wdm.h, Ntifs.h, or Fltkernel.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL