Função QueueUserWorkItem (threadpoollegacyapiset.h)

Enfileira um item de trabalho para um thread de trabalho no pool de threads.

Sintaxe

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

Parâmetros

[in] Function

Um ponteiro para a função de retorno de chamada definida pelo aplicativo do tipo LPTHREAD_START_ROUTINE a ser executado pelo thread no pool de threads. Esse valor representa o endereço inicial do thread. Essa função de retorno de chamada não deve chamar a função TerminateThread .

O valor retornado da função de retorno de chamada não é usado.

Para obter mais informações, consulte ThreadProc.

[in, optional] Context

Um único valor de parâmetro a ser passado para a função de thread.

[in] Flags

Os sinalizadores que controlam a execução. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
WT_EXECUTEDEFAULT 0x00000000	Por padrão, a função de retorno de chamada é enfileirada em um thread de trabalho que não é de E/S. A função de retorno de chamada é enfileirada em um thread que usa portas de conclusão de E/S, o que significa que elas não podem executar uma espera alertável. Portanto, se a E/S for concluída e gerar um APC, o APC poderá aguardar indefinidamente porque não há garantia de que o thread entrará em um estado de espera alertável após a conclusão do retorno de chamada.
WT_EXECUTEINIOTHREAD 0x00000001	Esse sinalizador não é usado. Windows Server 2003 e Windows XP: A função de retorno de chamada é enfileirada em um thread de trabalho de E/S. Esse sinalizador deve ser usado se a função deve ser executada em um thread que aguarda em um estado alertável. Os threads de trabalho de E/S foram removidos a partir do Windows Vista e do Windows Server 2008.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	A função de retorno de chamada é enfileirada em um thread que nunca termina. Ele não garante que o mesmo thread seja usado a cada vez. Esse sinalizador deve ser usado apenas para tarefas curtas ou pode afetar outras operações de temporizador. Esse sinalizador deverá ser definido se o thread chamar funções que usam APCs. Para obter mais informações, consulte Chamadas de procedimento assíncrono. Observe que atualmente nenhum thread de trabalho é realmente persistente, embora os threads de trabalho não terminem se houver solicitações de E/S pendentes.
WT_EXECUTELONGFUNCTION 0x00000010	A função de retorno de chamada pode executar uma longa espera. Esse sinalizador ajuda o sistema a decidir se ele deve criar um thread.
WT_TRANSFER_IMPERSONATION 0x00000100	As funções de retorno de chamada usarão o token de acesso atual, seja um processo ou token de representação. Se esse sinalizador não for especificado, as funções de retorno de chamada serão executadas somente com o token de processo. Windows XP: Esse sinalizador não tem suporte até o Windows XP SP2 e o Windows Server 2003.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Se uma função em uma DLL estiver na fila para um thread de trabalho, verifique se a função concluiu a execução antes que a DLL seja descarregada.

Por padrão, o pool de threads tem um máximo de 512 threads por processo. Para aumentar o limite de fila, use a macro WT_SET_MAX_THREADPOOL_THREAD definida em WinNT.h.

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

Use essa macro na chamada para QueueUserWorkItem para especificar o parâmetro Flags . Os parâmetros de macro são os sinalizadores desejados e o novo limite, até (2<<16)-1 threads. No entanto, o tamanho da fila é limitado pelo tamanho do pool nãopagado do kernel. Observe que seu aplicativo pode melhorar seu desempenho mantendo o número de threads de trabalho baixo.

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0500 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	threadpoollegacyapiset.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll

Confira também

Funções de thread e processo

Pooling de threads

Threadproc