ZwWaitForSingleObject, fonction (ntifs.h)

Article
07/11/2023

La routine ZwWaitForSingleObject attend que l’objet spécifié atteigne l’état Signaled. Un délai d’attente facultatif peut également être spécifié.

Syntaxe

NTSYSAPI NTSTATUS ZwWaitForSingleObject(
  [in]           HANDLE         Handle,
  [in]           BOOLEAN        Alertable,
  [in, optional] PLARGE_INTEGER Timeout
);

Paramètres

[in] Handle

Handle de l’objet .

[in] Alertable

Valeur booléenne qui spécifie si l’attente peut être alertée.

[in, optional] Timeout

Pointeur facultatif vers une valeur de délai d’attente qui spécifie l’heure absolue ou relative à laquelle l’attente doit être terminée. Une valeur négative spécifie un intervalle par rapport à l’heure actuelle. La valeur doit être exprimée en unités de 100 nanosecondes. Les délais d’expiration absolus suivent les modifications apportées à l’heure système. Les temps d’expiration relatifs ne sont pas affectés par les changements d’heure système.

Valeur retournée

ZwWaitForSingleObject peut retourner l’un des codes status possibles suivants :

Code de retour	Description
STATUS_ACCESS_DENIED	L’appelant ne disposait pas des privilèges requis pour l’événement spécifié par le paramètre Handle .
STATUS_ALERTED	L’attente a été abandonnée pour remettre une alerte au thread actuel.
STATUS_INVALID_HANDLE	Le paramètre Handle fourni n’était pas valide.
STATUS_SUCCESS	L’objet spécifié a satisfait à l’attente.
STATUS_TIMEOUT	Un délai d’attente s’est produit avant que l’objet soit défini sur un état signalé. Cette valeur peut être retournée lorsque le jeu de conditions d’attente spécifié ne peut pas être immédiatement rempli et que le paramètre Timeout est défini sur zéro.
STATUS_USER_APC	L’attente a été abandonnée pour remettre un APC utilisateur au thread actuel.

Notez que la macro NT_SUCCESS reconnaît les valeurs STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT et STATUS_USER_APC status comme valeurs de « réussite ».

Remarques

ZwWaitForSingleObject attend que l’objet spécifié atteigne l’état Signaled. Un délai d’expiration facultatif peut également être spécifié. ZwWaitForSingleObject examine l’état actuel de l’objet spécifié pour déterminer si l’attente peut être satisfaite immédiatement. Si c’est le cas, des actions sont effectuées. Sinon, le thread actuel est placé dans un état d’attente et un nouveau thread est sélectionné pour exécution sur le processeur actuel.

Si aucun paramètre Timeout n’est spécifié, l’attente ne sera pas satisfaite tant que l’objet n’aura pas atteint l’état Signaled. Si un paramètre Timeout est spécifié et que l’objet n’a pas atteint l’état Signaled à l’expiration du délai d’attente, l’attente est automatiquement satisfaite. Si une valeur de délai d’expiration explicite de zéro est spécifiée, aucune attente ne se produit si l’attente ne peut pas être satisfaite immédiatement. Une valeur de délai d’expiration égale à zéro permet de tester un ensemble de conditions d’attente et pour les performances conditionnelles des effets secondaires si l’attente peut être immédiatement satisfaite, comme dans l’acquisition d’un mutex. L’attente peut également être spécifiée comme pouvant être alertée.

Le paramètre Alertable spécifie si le thread peut être alerté et si son état d’attente est donc abandonné. Si la valeur de ce paramètre est FALSE, le thread ne peut pas être alerté. La seule exception à cette règle est celle d’un thread de fin. Dans certaines circonstances, un thread de fin peut être alerté pendant qu’il est en cours d’arrêt. Un thread est automatiquement mis en alerte, pour instance, lorsqu’il est arrêté par un utilisateur avec une touche CTRL+C.

Si la valeur de Alertableest TRUE et que l’une des conditions suivantes est présente, le thread est alerté :

Si l’origine de l’alerte est une routine interne et non documentée en mode noyau utilisée pour alerter les threads.
L’origine de l’alerte est un APC en mode utilisateur.

Dans le premier de ces deux cas, l’attente du thread est satisfaite par une status d’achèvement de STATUS_ALERTED. Dans le deuxième cas, il est satisfait d’une status d’achèvement de STATUS_USER_APC.

Le thread doit être alertable pour qu’un APC en mode utilisateur soit remis. Ce n’est pas le cas pour les API en mode noyau. Un APC en mode noyau peut être remis et exécuté même si le thread n’est pas alerté. Une fois l’exécution de l’APC terminée, l’attente du thread reprend. Un thread n’est jamais alerté, ni abandonné par la remise d’un APC en mode noyau.

La remise des API en mode noyau à un thread en attente ne dépend pas de la possibilité d’alerter ou non le thread. Si l’APC en mode noyau est un APC spécial en mode noyau, l’APC est fourni à condition que l’IRQL soit inférieur à APC_LEVEL. Si l’APC en mode noyau est un APC en mode noyau normal, l’APC est fourni à condition que les trois conditions suivantes soient remplies : (1) l’IRQL est inférieur à APC_LEVEL, (2) aucun APC de noyau n’est en cours et (3) le thread n’est pas dans une section critique.

Si le handle passé à ZwWaitForSingleObject fait référence à un mutex, la livraison APC est la même que pour tous les autres objets de répartiteur pendant l’attente. Toutefois, une fois que ZwWaitForSingleObject est retourné avec STATUS_SUCCESS et que le thread contient réellement le mutex, seuls les API spéciales en mode noyau sont remises. La remise de tous les autres API, à la fois en mode noyau et en mode utilisateur, est désactivée. Cette restriction sur la remise des API persiste jusqu’à ce que le mutex soit libéré.

Il est particulièrement important de case activée la valeur de retour de ZwWaitForSingleObject lorsque le paramètre Alertable a la valeur TRUE, car ZwWaitForSingleObject peut revenir plus tôt avec un status de STATUS_USER_APC ou de STATUS_ALERTED.

Toutes les attentes à long terme peuvent être abandonnées par un utilisateur si le paramètre Alertable est défini sur FALSE.

Pour plus d’informations, consultez Les threads en attente reçoivent-ils des alertes et des API ?

Les appelants de ZwWaitForSingleObject doivent s’exécuter sur IRQL inférieur ou égal à DISPATCH_LEVEL. En règle générale, l’appelant doit s’exécuter sur irQL PASSIVE_LEVEL et dans un contexte de thread nonarbitrary. Un appel en cours d’exécution sur irQL DISPATCH_LEVEL est valide si et seulement si l’appelant spécifie un paramètre De délai d’expiration de zéro. Autrement dit, un pilote ne doit pas attendre un intervalle différent de zéro à IRQL égal à DISPATCH_LEVEL.

Les intervalles de délai d’attente sont mesurés par rapport à l’horloge système, et la précision de la mesure du délai d’attente est limitée par la granularité de l’horloge système. Pour plus d’informations, consultez Précision du minuteur.

Si l’appel à la fonction ZwWaitForSingleObject se produit en mode utilisateur, vous devez utiliser le nom « NtWaitForSingleObject » au lieu de « ZwWaitForSingleObject ».

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP
Plateforme cible	Universal
En-tête	ntifs.h (include Ntifs.h, FltKernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), SpNoWait(storport)