IoInitializeWorkItem function (wdm.h)

Article
02/25/2022

The IoInitializeWorkItem routine initializes a work item that the caller has already allocated.

Syntax

void IoInitializeWorkItem(
  [in] PVOID        IoObject,
  [in] PIO_WORKITEM IoWorkItem
);

Parameters

[in] IoObject

Pointer to the caller's driver object or to one of the caller's device objects. If the caller will later pass the work item to IoQueueWorkItem, IoObject must point to a device object.

[in] IoWorkItem

Pointer to the IO_WORKITEM structure to initialize.

Return value

None

Remarks

The driver allocates its own storage for an IO_WORKITEM structure, and then calls IoInitializeWorkItem to initialize it. Memory must be allocated from nonpaged pool. To determine the number of bytes that is necessary to hold an IO_WORKITEM structure, call IoSizeofWorkItem.

An IO_WORKITEM structure that is initialized by IoInitializeWorkItem must be uninitialized by IoUninitializeWorkItem before it is freed.

A related routine, IoAllocateWorkItem, both allocates and initializes a work item. By combining allocation and initialization into a single call, IoAllocateWorkItem might be more convenient for some drivers to use than IoInitializeWorkItem, which does initialization only. However, IoInitializeWorkItem is required by drivers that must initialize work items in previously allocated storage.

For example, a driver might allocate a block of storage for a pool of work items. The driver can call IoInitializeWorkItem to initialize a work item when the work item is allocated from the pool. The driver can call IoUninitializeWorkItem to uninitialize the work item when it is returned to the pool. During the initial storage allocation for the pool, the driver can call IoSizeofWorkitem to determine how much storage to allocate for each work item.

For more information about work items, see System Worker Threads.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of Windows.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Any level