QueueUserWorkItem

The QueueUserWorkItem function queues a work item to a worker thread in the thread pool.

BOOL QueueUserWorkItem(
  LPTHREAD_START_ROUTINE Function,  // starting address
  PVOID Context,                    // function data
  ULONG Flags                       // worker options
);

Parameters

Function

[in] Pointer to the application-defined callback function of type LPTHREAD_START_ROUTINE to be executed by the thread in the thread pool. This value represents the starting address of the thread. This callback function must not call the TerminateThread function.

For more information, see ThreadProc.

Context

[in] Specifies a single parameter value that will be passed to the thread function.

Flags

[in] This parameter can be one or more of the following values.

Value	Meaning
WT_EXECUTEDEFAULT	By default, the callback function is queued to a non-I/O worker thread.
WT_EXECUTEINIOTHREAD	The callback function is queued to an I/O worker thread. This flag should be used if the function should be executed in a thread that waits in an alertable state. The callback function is queued as an APC. Be sure to address reentrancy issues if the function performs an alertable wait operation.
WT_EXECUTEINPERSISTENTTHREAD	The callback function is queued to a thread that never terminates. This flag should be used only for short tasks or it could affect other timer operations. Note that currently no worker thread is truly persistent, although worker threads do not terminate if there are any pending I/O requests.
WT_EXECUTELONGFUNCTION	Specifies that the callback function can perform a long wait. This flag helps the system to decide if it should create a new thread.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If a function in a DLL is queued to a worker thread, be sure that the function has completed execution before the DLL is unloaded.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

Processes and Threads Overview, Process and Thread Functions, ThreadProc, Thread Pooling