RegisterWaitForSingleObject, fonction (winbase.h)

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 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

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

Voir aussi

fonctions de synchronisation

de regroupement de threads

DésinscrireWait

DésinscrireWaitEx

Fonctions d’attente

WaitOrTimerCallback