RegisterWaitForSingleObject, fonction (winbase.h)
Indique à un thread d’attente dans le pool de threads d’attendre sur l’objet . Le thread d’attente met en file d’attente la fonction de rappel spécifiée vers le pool de threads lorsque l’un des événements suivants se produit :
- L’objet spécifié est à 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 au retour. Notez qu’un handle d’attente ne peut pas être utilisé dans les fonctions qui nécessitent un handle d’objet, comme CloseHandle.
[in] hObject
Handle de l’objet . Pour obtenir la liste des types d’objets dont les handles peuvent être spécifiés, consultez la section Remarques suivante.
Si ce handle est fermé alors que l’attente est toujours en attente, le comportement de la fonction n’est pas défini.
Les handles doivent avoir le droit d’accès SYNCHRONIZE . Pour plus d’informations, consultez Droits d’accès standard.
[in] Callback
Pointeur vers la fonction définie par l’application de type WAITORTIMERCALLBACK à exécuter lorsque hObject est dans l’état signalé ou que dwMilliseconds s’écoule . Pour plus d’informations, consultez WaitOrTimerCallback.
[in, optional] Context
Valeur unique passée à 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 a la valeur INFINITE, l’intervalle de délai d’attente de la fonction ne s’écoule jamais.
[in] dwFlags
Ce paramètre peut prendre 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 |
|---|---|
|
Par défaut, la fonction de rappel est mise en file d’attente vers un thread de travail non-E/S. |
|
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 ne doit être utilisé que pour les tâches courtes ou peut 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’aucun thread de travail n’est réellement persistant, bien qu’aucun thread de travail ne se termine s’il y a des demandes d’E/S en attente. |
|
La fonction de rappel est appelée par le thread d’attente lui-même. Cet indicateur ne doit être utilisé que pour les tâches courtes ou peut affecter d’autres opérations d’attente.
Des interblocages peuvent se produire si un autre thread acquiert un verrou exclusif et appelle la fonction UnregisterWait ou UnregisterWaitEx pendant que la fonction de rappel tente d’acquérir le même verrou. |
|
La fonction de rappel peut effectuer une longue attente. Cet indicateur aide le système à décider s’il doit créer un thread. |
|
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. |
|
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 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’erreur étendues, appelez
GetLastError.
Remarques
Les nouveaux threads d’attente sont créés automatiquement lorsque cela est nécessaire. L’opération d’attente est effectuée par un thread d’attente du pool de threads. La routine de rappel est exécutée par un thread de travail lorsque l’état de l’objet est 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 UnregisterWait ou 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 é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 arrêté), 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 réduit d’un.
La fonction RegisterWaitForSingleObject peut attendre les objets suivants :
- Notification de modification
- Entrée de console
- Événement
- Notification de ressource mémoire
- Mutex
- Processus
- Semaphore
- Thread
- Minuteur d’attente
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 limitant le nombre de threads de travail.
L’élément de travail et toutes les fonctions qu’il appelle doivent être sécurisés 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 la valeur maximale du pool de threads au minimum du pool de threads à l’aide des fonctions SetThreadpoolThreadMaximum et SetThreadpoolThreadMinimum , ou créez votre propre thread à l’aide de la fonction CreateThread . (Pour l’API du 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 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 | winbase.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour