Функция QueueUserWorkItem (threadpoollegacyapiset.h)

  • Статья

Помещает рабочий элемент в очередь в рабочий поток в пуле потоков.

Синтаксис

BOOL QueueUserWorkItem(
  [in]           LPTHREAD_START_ROUTINE Function,
  [in, optional] PVOID                  Context,
  [in]           ULONG                  Flags
);

Параметры

[in] Function

Указатель на определяемую приложением функцию обратного вызова типа LPTHREAD_START_ROUTINE выполняться потоком в пуле потоков. Это значение представляет начальный адрес потока. Эта функция обратного вызова не должна вызывать функцию TerminateThread .

Возвращаемое значение функции обратного вызова не используется.

Дополнительные сведения см. в разделе ThreadProc.

[in, optional] Context

Значение одного параметра, передаваемое функции потока.

[in] Flags

Флаги, управляющие выполнением. Этот параметр может быть одним или несколькими из следующих значений.

Значение Значение
WT_EXECUTEDEFAULT
0x00000000
 По умолчанию функция обратного вызова помещается в очередь в рабочий поток, отличный от ввода-вывода.

Функция обратного вызова помещается в очередь в поток, использующий порты завершения ввода-вывода, что означает, что они не могут выполнять ожидание с оповещениями. Таким образом, если ввод-вывод завершится и создаст APC, APC может ждать неограниченное время, так как нет никакой гарантии, что поток перейдет в состояние ожидания с оповещением после завершения обратного вызова.
WT_EXECUTEINIOTHREAD
0x00000001
 Этот флаг не используется.

Windows Server 2003 и Windows XP: Функция обратного вызова помещается в очередь в рабочий поток ввода-вывода. Этот флаг следует использовать, если функция должна выполняться в потоке, который ожидает оповещения.

Рабочие потоки ввода-вывода были удалены начиная с Windows Vista и Windows Server 2008.
WT_EXECUTEINPERSISTENTTHREAD
0x00000080
 Функция обратного вызова помещается в очередь в поток, который никогда не завершается. Это не гарантирует, что один и тот же поток будет использоваться каждый раз. Этот флаг следует использовать только для коротких задач, иначе он может повлиять на другие операции таймера.

Этот флаг необходимо установить, если поток вызывает функции, использующие APC. Дополнительные сведения см. в разделе Асинхронные вызовы процедур.

Обратите внимание, что в настоящее время ни один рабочий поток не является действительно постоянным, хотя рабочие потоки не завершаются при наличии ожидающих запросов ввода-вывода.
WT_EXECUTELONGFUNCTION
0x00000010
 Функция обратного вызова может выполнять длительное ожидание. Этот флаг помогает системе решить, следует ли создавать новый поток.
WT_TRANSFER_IMPERSONATION
0x00000100
 Функции обратного вызова будут использовать текущий маркер доступа, будь то маркер процесса или маркер олицетворения. Если этот флаг не указан, функции обратного вызова выполняются только с маркером процесса.

Windows XP: Этот флаг не поддерживается до Windows XP с пакетом обновления 2 (SP2) и Windows Server 2003.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Если функция в библиотеке DLL помещается в очередь в рабочий поток, убедитесь, что выполнение функции завершено до выгрузки библиотеки DLL.

По умолчанию пул потоков содержит не более 512 потоков на процесс. Чтобы увеличить ограничение очереди, используйте макрос WT_SET_MAX_THREADPOOL_THREAD , определенный в WinNT.h.

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

Используйте этот макрос в вызове QueueUserWorkItem , чтобы указать параметр Flags . Параметры макроса — это нужные флаги и новое ограничение, вплоть до (2<<16)-1 потоков. Однако размер очереди ограничен размером непагрегированного пула ядра. Обратите внимание, что приложение может повысить производительность, сохраняя низкое количество рабочих потоков.

Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0500 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header threadpoollegacyapiset.h (включая Windows.h в Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также

Функции процессов и потоков

Группировка потоков в пул

ThreadProc