ExInitializeWorkItem function (wdm.h)

Article
02/22/2024

ExInitializeWorkItem initializes a work-queue item with a caller-supplied context and callback routine to be queued for execution when a system worker thread is given control.

Warning

Use this routine with extreme caution. See the Remarks section below.

Syntax

void ExInitializeWorkItem(
  [in] PWORK_QUEUE_ITEM       Item,
  [in] PWORKER_THREAD_ROUTINE Routine,
  [in] PVOID                  Context
);

Parameters

[in] Item

Pointer to a caller-allocated WORK_QUEUE_ITEM structure to be initialized. This structure must be allocated from nonpaged pool. The callback routine specified in the Routine parameter is responsible for freeing this work item when it is no longer needed by calling ExFreePool or ExFreePoolWithTag.

[in] Routine

Pointer to a caller-defined routine that will be called to process the work item. This routine will be called in the context of a system thread at IRQL PASSIVE_LEVEL. This routine is declared as follows:

VOID
(*PWORKER_THREAD_ROUTINE)(
    IN PVOID Parameter
    );

Parameter

Context information pointer that was passed in the Context parameter.

[in] Context

Pointer to caller-supplied context information to be passed to the callback routine specified in the Routine parameter.

Return value

None

Remarks

ExInitializeWorkItem initializes the work item with the specified callback routine and context pointer and NULL list pointers.

To add the work item to a system work queue, call ExQueueWorkItem.

Work items are a limited resource, and drivers should only allocate them as needed. For example, do not allocate a work item in DriverEntry for the driver's dedicated use.

ExInitializeWorkItem and ExQueueWorkItem can only be used in cases where the specified work item is not associated with any 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.

Requirements

Requirement	Value
Target Platform	Desktop
Header	wdm.h (include FltKernel.h, Ntifs.h, Ntddk.h, Wdm.h)
IRQL	Any level