Fonction QueueUserWorkItem (threadpoollegacyapiset.h)

Met en file d’attente un élément de travail vers un thread de travail dans le pool de threads.

Syntaxe

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

Paramètres

[in] Function

Pointeur vers la fonction de rappel définie par l’application de type LPTHREAD_START_ROUTINE à exécuter par le thread dans le pool de threads. Cette valeur représente l’adresse de départ du thread. Cette fonction de rappel ne doit pas appeler la fonction TerminateThread .

La valeur de retour de la fonction de rappel n’est pas utilisée.

Pour plus d’informations, consultez ThreadProc.

[in, optional] Context

Valeur de paramètre unique à passer à la fonction thread.

[in] Flags

Indicateurs qui contrôlent l’exécution. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur	Signification
WT_EXECUTEDEFAULT 0x00000000	Par défaut, la fonction de rappel est mise en file d’attente vers un thread de travail non-E/S. La fonction de rappel est mise en file d’attente vers un thread qui utilise des ports d’achèvement d’E/S, ce qui signifie qu’il ne peut pas effectuer une attente pouvant être alertée. Par conséquent, si les E/S se terminent et génèrent un APC, l’APC peut attendre indéfiniment, car il n’y a aucune garantie que le thread entre dans un état d’attente pouvant être alerté une fois le rappel terminé.
WT_EXECUTEINIOTHREAD 0x00000001	Cet indicateur n’est pas utilisé. Windows Server 2003 et Windows XP : La fonction de rappel est mise en file d’attente vers un thread de travail d’E/S. Cet indicateur doit être utilisé si la fonction doit être exécutée dans un thread qui attend dans un état alerte. Les threads de travail d’E/S ont été supprimés à partir de Windows Vista et Windows Server 2008.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	La fonction de rappel est mise en file d’attente vers un thread qui ne se termine jamais. Il ne garantit pas que le même thread est utilisé à chaque fois. Cet indicateur doit être utilisé uniquement pour les tâches courtes ou peut affecter d’autres opérations du minuteur. Cet indicateur doit être défini si le thread appelle des fonctions qui utilisent des API. Pour plus d’informations, consultez Appels de procédure asynchrone. Notez qu’aucun thread de travail n’est réellement persistant, bien que les threads de travail ne se terminent pas s’il y a des demandes d’E/S en attente.
WT_EXECUTELONGFUNCTION 0x00000010	La fonction de rappel peut effectuer une longue attente. Cet indicateur aide le système à décider s’il doit créer un thread.
WT_TRANSFER_IMPERSONATION 0x00000100	Les fonctions de rappel utilisent le jeton d’accès actuel, qu’il s’agisse d’un processus ou d’un jeton d’emprunt d’identité. Si cet indicateur n’est pas spécifié, les fonctions de rappel s’exécutent uniquement avec le jeton de processus. Windows XP : Cet indicateur n’est pas pris en charge tant que Windows XP SP2 et Windows Server 2003.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Si une fonction d’une DLL est mise en file d’attente vers un thread de travail, assurez-vous que l’exécution de la fonction est terminée avant que la DLL ne soit déchargée.

Par défaut, le pool de threads a un maximum de 512 threads par processus. Pour augmenter la limite de file d’attente, utilisez la macro WT_SET_MAX_THREADPOOL_THREAD définie dans WinNT.h.

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

Utilisez cette macro dans l’appel à QueueUserWorkItem pour spécifier le paramètre Flags . Les paramètres de macro sont les indicateurs souhaités et la nouvelle limite, jusqu’à (2<<16)-1 threads. Toutefois, la taille de la file d’attente est limitée par la taille du pool sans paginé du noyau. Notez que votre application peut améliorer ses performances en maintenant le nombre de threads de travail bas.

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0500 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	threadpoollegacyapiset.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

Fonctions de processus et de thread

Regroupement des threads

ThreadProc