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 |
|---|---|
|
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é. |
|
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. |
|
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. |
|
La fonction de rappel peut effectuer une longue attente. Cet indicateur aide le système à décider s’il doit créer un thread. |
|
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 |