3 out of 7 rated this helpful Rate this topic

QueueUserWorkItem function

Queues a work item to a worker thread in the thread pool.

Syntax

Copy

BOOL WINAPI QueueUserWorkItem(
  __in      LPTHREAD_START_ROUTINE Function,
  __in_opt  PVOID Context,
  __in      ULONG Flags
);

Parameters

Function [in]

A 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, optional]

A single parameter value to be passed to the thread function.

Flags [in]

The flags that control execution. This parameter can be one or more of the following values.

Value	Meaning
WT_EXECUTEDEFAULT 0x00000000	By default, the callback function is queued to a non-I/O worker thread. The callback function is queued to a thread that uses I/O completion ports, which means they cannot perform an alertable wait. Therefore, if I/O completes and generates an APC, the APC might wait indefinitely because there is no guarantee that the thread will enter an alertable wait state after the callback completes.
WT_EXECUTEINIOTHREAD 0x00000001	This flag is not used. Windows Server 2003 and Windows XP/2000: 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. I/O worker threads were removed starting with Windows Vista and Windows Server 2008.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	The callback function is queued to a thread that never terminates. It does not guarantee that the same thread is used each time. This flag should be used only for short tasks or it could affect other timer operations. This flag must be set if the thread calls functions that use APCs. For more information, see Asynchronous Procedure Calls. 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 0x00000010	The callback function can perform a long wait. This flag helps the system to decide if it should create a new thread.
WT_TRANSFER_IMPERSONATION 0x00000100	Callback functions will use the current access token, whether it is a process or impersonation token. If this flag is not specified, callback functions execute only with the process token. Windows XP/2000: This flag is not supported until Windows XP SP2 and Windows Server 2003.

Return value

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.

By default, the thread pool has a maximum of 512 threads per process. To raise the queue limit, use the WT_SET_MAX_THREADPOOL_THREAD macro defined in Winnt.h.

Copy

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

Use this macro in the call to QueueUserWorkItem to specify the Flags parameter. The macro parameters are the desired flags and the new limit, up to (2<<16)-1 threads. However, the size of the queue is limited by the size of the kernel nonpaged pool. Note that your application can improve its performance by keeping the number of worker threads low.

To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Winbase.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

The thread pool will spawn as many threads as there are CPUs in the system. For example, if you have an Intel 97-core CPU, and you queue a million work items, the thread pool will spin up 97 threads in order to give work to all CPUs. If this was not the case, then the thread pool would only being using 1/97th of your CPU's available power.

This is very useful for something like image processing, where the image could be sub-divided into thousands of 16x16 regions, each can be worked on independantly as a queued work item. This way the processing happens in parallel on multi-cpu machines, but degrades into a serial operation on single-cpu machines.

History

4/21/2007
Jack Tripper

12/21/2008
gäst

Number of threads (above comment incorrect).

The thread pool does not spawn as many threads as there are CPUs in the system. As documented, there are 512 max by default (although you can change the maximum limit). The number of threads actually spawned is affected by a number of things, and no guarantees are made that it's tied to CPU count. In fact, if you specify WT_EXECUTELONGFUNCTION, the system will be much less reluctant to create new threads, and it is highly likely you'll end up with more threads than CPU's.

The above comment is incorrect; the number of threads spawned is unrelated to the number of CPUs that you have. Also, in many circumstances you would not want it to be bound to the number of CPUs anyways. If all of your work items are CPU-bound then it does make sense to have as many threads as CPUs. If your items, however, are I/O bound, maybe network bound or waiting for external, then you will likely want far more threads than CPUs to maximize the benefits.

What the above post says about the usefulness of thread pools, however, is perfectly valid.