RegisterWaitForSingleObject, fonction (winbase.h)

Article
11/08/2024

Dirige un thread d’attente dans le pool de threads attendre sur l’objet. Le thread d’attente met en file d’attente la fonction de rappel spécifiée au pool de threads lorsque l’une des opérations suivantes se produit :

L’objet spécifié est dans l’état signalé.
L’intervalle de délai d’attente s’écoule.

Syntaxe

BOOL RegisterWaitForSingleObject(
  [out]          PHANDLE             phNewWaitObject,
  [in]           HANDLE              hObject,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Context,
  [in]           ULONG               dwMilliseconds,
  [in]           ULONG               dwFlags
);

Paramètres

[out] phNewWaitObject

Pointeur vers une variable qui reçoit un handle d’attente lors du retour. Notez qu’un handle d’attente ne peut pas être utilisé dans les fonctions qui nécessitent un handle d’objet, tel que CloseHandle.

[in] hObject

Handle vers l’objet. Pour obtenir la liste des types d’objets dont les handles peuvent être spécifiés, consultez la section Remarques suivante.

Mutex n’est pas pris en charge. Si un handle vers un mutex est passé, le pool de threads déclenche une exception STATUS_THREADPOOL_HANDLE_EXCEPTION et ExceptionRecord.ExceptionInformation[0] est égal à STATUS_INVALID_PARAMETER_3.

Si ce handle est fermé pendant que l’attente est toujours en attente, le comportement de la fonction n’est pas défini.

Les handles doivent disposer du droit d’accès SYNCHRONIZE. Pour plus d’informations, consultez Standard Access Rights.

[in] Callback

Pointeur vers la fonction définie par l’application de type WAITORTIMERCALLBACK à exécuter lorsque hObject est dans l’état signalé, ou dwMilliseconds s’écoule. Pour plus d’informations, consultez WaitOrTimerCallback.

[in, optional] Context

Valeur unique transmise à la fonction de rappel.

[in] dwMilliseconds

Intervalle de délai d’attente, en millisecondes. La fonction retourne si l’intervalle s’écoule, même si l’état de l’objet n’est pas signé. Si dwMilliseconds est égal à zéro, la fonction teste l’état de l’objet et retourne immédiatement. Si dwMilliseconds est INFINITE, l’intervalle de délai d’attente de la fonction n’est jamais écoulé.

[in] dwFlags

Ce paramètre peut être une ou plusieurs des valeurs suivantes.

Pour plus d’informations sur l’utilisation de ces valeurs avec des objets qui restent signalés, consultez la section Remarques.

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.
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 d’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 affecter d’autres opérations d’attente. 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’actuellement aucun thread de travail n’est vraiment persistant, bien qu’aucun thread de travail ne se termine s’il existe des demandes d’E/S en attente.
WT_EXECUTEINWAITTHREAD 0x00000004	La fonction de rappel est appelée par le thread d’attente lui-même. Cet indicateur doit être utilisé uniquement pour les tâches courtes ou affecter d’autres opérations d’attente. Des interblocages peuvent se produire si un autre thread acquiert un verrou exclusif et appelle le UnregisterWait ou Fonction UnregisterWaitEx pendant que la fonction de rappel tente d’acquérir le même verrou.
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_EXECUTEONLYONCE 0x00000008	Le thread n’attend plus sur le handle une fois que la fonction de rappel a été appelée une seule fois. Sinon, le minuteur est réinitialisé chaque fois que l’opération d’attente se termine jusqu’à ce que l’opération d’attente soit annulée.
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 avec SP2 et Windows Server 2003.

Valeur de retour

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’erreur étendues, appelez
GetLastError.

Remarques

Les nouveaux threads d’attente sont créés automatiquement lorsque nécessaire. L’opération d’attente est effectuée par un thread d’attente à partir du pool de threads. La routine de rappel est exécutée par un thread de travail lorsque l’état de l’objet devient signalé ou que l’intervalle de délai d’attente s’écoule. Si dwFlags n’est pas WT_EXECUTEONLYONCE, le minuteur est réinitialisé chaque fois que l’événement est signalé ou que l’intervalle de délai d’attente s’écoule.

Une fois l’attente terminée, vous devez appeler la fonction Annuler l’inscriptionWait ou Fonction UnregisterWaitEx pour annuler l’opération d’attente. (Même les opérations d’attente qui utilisent WT_EXECUTEONLYONCE doivent être annulées.) N’effectuez pas d’appel bloquant à l’une de ces fonctions à partir de la fonction de rappel.

Notez que vous ne devez pas pulser un objet d’événement passé à RegisterWaitForSingleObject, car le thread d’attente peut ne pas détecter que l’événement est signalé avant sa réinitialisation. Vous ne devez pas inscrire un objet qui reste signalé (par exemple, un événement de réinitialisation manuelle ou un processus terminé), sauf si vous définissez l’indicateur WT_EXECUTEONLYONCE ou WT_EXECUTEINWAITTHREAD. Pour les autres indicateurs, la fonction de rappel peut être appelée trop de fois avant la réinitialisation de l’événement.

La fonction modifie l’état de certains types d’objets de synchronisation. La modification se produit uniquement pour l’objet dont l’état signalé a provoqué la satisfaction de la condition d’attente. Par exemple, le nombre d’un objet sémaphore est diminué d’un.

La fonction RegisterWaitForSingleObject peut attendre les objets suivants :

Notification de modification
Entrée de console
Événement
Notification de ressource mémoire
Processus
Sémaphore
Fil
Minuteur pouvant être attendu

Pour plus d’informations, consultez Objets de synchronisation.

Par défaut, le pool de threads a un maximum de 500 threads. Pour augmenter cette limite, 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 lors de la spécification du paramètre dwFlags. Les paramètres de macro sont les indicateurs souhaités et la nouvelle limite (jusqu’à (2<<16)-1 threads). Toutefois, notez que votre application peut améliorer ses performances en conservant le nombre de threads de travail bas.

L’élément de travail et toutes les fonctions qu’il appelle doivent être sécurisées pour le pool de threads. Par conséquent, vous ne pouvez pas appeler un appel asynchrone qui nécessite un thread persistant, tel que la fonction RegNotifyChangeKeyValue, à partir de l’environnement de rappel par défaut. Au lieu de cela, définissez le pool de threads maximal égal au minimum du pool de threads à l’aide de la SetThreadpoolThreadpoolThreadMaximum et fonctions SetThreadpoolThreadMinimum, ou créez votre propre thread à l’aide de la fonction CreateThread . (Pour l’API de pool de threads d’origine, spécifiez WT_EXECUTEINPERSISTENTTHREAD à l’aide de la fonction QueueUserWorkItem .)

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

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll