KeWaitForSingleObject, fonction (wdm.h)

La routine KeWaitForSingleObject place le thread actuel dans un état d’attente jusqu’à ce que l’objet répartiteur donné soit défini sur un état signalé ou (éventuellement) jusqu’au délai d’attente.

Syntaxe

NTSTATUS
KeWaitForSingleObject (
    PVOID Object,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout
    );

Paramètres

[in] Object

Pointeur vers un objet de répartiteur initialisé (événement, mutex, sémaphore, thread ou minuteur) pour lequel l’appelant fournit le stockage.

[in] WaitReason

Spécifie la raison de l’attente. Un pilote doit définir cette valeur sur Executive, sauf si elle fonctionne au nom d’un utilisateur et s’exécute dans le contexte d’un thread utilisateur, auquel cas elle doit définir cette valeur sur UserRequest.

[in] WaitMode

Spécifie si l’appelant attend dans KernelMode ou UserMode. Les pilotes de niveau le plus bas et intermédiaire doivent spécifier KernelMode. Si l’objet donné est un mutex, l’appelant doit spécifier KernelMode.

[in] Alertable

Spécifie une valeur booléenne true si l’attente est alertable et FALSE sinon.

[in, optional] Timeout

Pointeur vers une valeur de délai d’expiration qui spécifie l’heure absolue ou relative, en 100 nanosecondes, à laquelle l’attente doit être terminée.

Une valeur positive spécifie une heure absolue, relative au 1er janvier 1601. Une valeur négative spécifie un intervalle par rapport à l’heure actuelle. Les heures d’expiration absolues suivent les modifications apportées à l’heure système ; les délais d’expiration relatifs ne sont pas affectés par les modifications de temps système.

Si *Timeout = 0, la routine retourne sans attendre. Si l’appelant fournit un pointeur NULL , la routine attend indéfiniment jusqu’à ce que l’objet répartiteur soit défini sur l’état signalé. Pour plus d'informations, consultez la section Notes qui suit.

Valeur de retour

KeWaitForSingleObject peut retourner l’un des éléments suivants.

Notes

La macro NT_SUCCESS reconnaît toutes ces valeurs d’état comme des valeurs de « réussite ».

Code de retour Description
STATUS_SUCCESS L’objet répartiteur spécifié par le paramètre Object a satisfait l’attente.
STATUS_ALERTED L’attente a été interrompue pour remettre une alerte au thread appelant.
STATUS_USER_APC L’attente a été interrompue pour remettre un appel de procédure asynchrone utilisateur (APC) au thread appelant.
STATUS_TIMEOUT Un délai d’expiration s’est produit avant que l’objet ait été défini sur un état signalé. Cette valeur peut être retournée lorsque l’ensemble spécifié de conditions d’attente ne peut pas être immédiatement remplie et que le délai d’attente est défini sur zéro.

Remarques

L’état actuel de l’objet spécifié est examiné pour déterminer si l’attente peut être satisfaite immédiatement. Dans ce cas, les effets secondaires nécessaires sont effectués sur l’objet. Sinon, le thread actuel est placé dans un état d’attente et un nouveau thread est sélectionné pour l’exécution sur le processeur actuel.

Le paramètre Alertable détermine quand le thread peut être alerté et son état d’attente a par conséquent été abandonné. Pour plus d’informations, consultez Attends et API.

Une considération spéciale s’applique lorsque le paramètre Object transmis à KeWaitForSingleObject est un mutex. Si l’objet répartiteur attendu est un mutex, la livraison d’APC est identique à celle de tous les autres objets de répartiteur pendant l’attente. Toutefois, après que KeWaitForSingleObject retourne avec STATUS_SUCCESS et que le thread contient réellement le mutex, seules les API en mode noyau spécial sont livrées. La remise de toutes les autres API, 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é.

Si le paramètre WaitMode est UserMode, la pile du noyau peut être échangée pendant l’attente. Par conséquent, un appelant ne doit jamais tenter de transmettre des paramètres sur la pile lors de l’appel de KeWaitForSingleObject à l’aide de l’argument UserMode . Si vous allouez l’événement sur la pile, vous devez définir le paramètre WaitMode sur KernelMode.

Il est particulièrement important de vérifier la valeur de retour de KeWaitForSingleObject lorsque le paramètre WaitMode est UserMode ou Alertable est TRUE, car KeWaitForSingleObject peut retourner tôt avec un état de STATUS_USER_APC ou de STATUS_ALERTED.

Toutes les attente à long terme qui peuvent être abandonnées par un utilisateur doivent être des attentes UserMode et Alertable doivent être définies sur FALSE.

Si possible, Alertable doit être défini sur FALSE et WaitMode doit être défini sur KernelMode, afin de réduire la complexité du pilote. L’exception principale à ceci est lorsque l’attente est une attente à long terme.

Si un pointeur NULL est fourni pour le délai d’expiration, le thread appelant reste dans un état d’attente jusqu’à ce que l’objet soit signalé.

Une valeur de délai d’expiration de zéro permet le test d’un ensemble de conditions d’attente et pour les performances conditionnelles de tous les effets secondaires si l’attente peut être immédiatement satisfaite, comme dans l’acquisition d’un mutex.

Les intervalles de délai d’expiration sont mesurés par rapport à l’horloge système et la précision avec laquelle le système d’exploitation peut détecter la fin d’un intervalle de délai d’attente est limitée par la granularité de l’horloge système. Pour plus d’informations, consultez Précision du minuteur.

Un mutex peut être acquis de manière récursive uniquement en temps MINLONG. Si cette limite est dépassée, la routine déclenche une exception STATUS_MUTANT_LIMIT_EXCEEDED.

Les appelants de KeWaitForSingleObject doivent s’exécuter à IRQL <= DISPATCH_LEVEL. Toutefois, si TimeoutNULL ou *Timeout = != 0, l’appelant doit s’exécuter sur IRQL <= APC_LEVEL et dans un contexte de thread nonarbitraire. (Si timeout != NULL et *Timeout = 0, l’appelant doit s’exécuter à IRQL <= DISPATCH_LEVEL.)

KeWaitForMutexObject est une macro qui convertit en KeWaitForSingleObject, qui peut être utilisée à la place.

Pour de meilleures performances, utilisez des mutex rapides ou des mutex surveillés. Pour plus d’informations, consultez Alternatives aux objets Mutex.

Pour plus d’informations sur les objets mutex, consultez Mutex Objects.

Configuration requise

   
Client minimal pris en charge Disponible à partir de Windows 2000.
Plateforme cible Universal
En-tête wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL Consultez la section Remarques.
Règles de conformité DDI CompleteRequestStatusCheck(wdm), HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm),IoBuildDeviceControlWaitTimeout(wdm),IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), IrpProcessingComplete(wdm), IrqlKeWaitForMutexObject(wdm), LowerDriverReturn(wdm), MarkIrpPending2(wdm),PendedCompletedRequest(wdm), PendedCompletedRequest2(wdm), PendedCompletedRequest3(wdm),PendedCompletedRequestEx(wdm), RemoveLockForwardDeviceControl(wdm), RemoveLockForwardDeviceControlInternal(wdm), RemoveLockForwardRead(wdm), RemoveLockForwardWrite(wdm), RemoveLockForwardWrite(wdm), SpNoWait(storport), StartDeviceWait(wdm), StartDeviceWait2(wdm), StartDeviceWait3(wdm), StartDeviceWait4(wdm)

Voir aussi

ExInitializeFastMutex

KeBugCheckEx

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer

KeWaitForMultipleObjects