KeReleaseSemaphore, fonction (wdm.h)
La routine KeReleaseSemaphore libère l’objet sémaphore spécifié.
Syntaxe
LONG KeReleaseSemaphore(
[in, out] PRKSEMAPHORE Semaphore,
[in] KPRIORITY Increment,
[in] LONG Adjustment,
[in] BOOLEAN Wait
);
Paramètres
[in, out] Semaphore
Pointeur vers un objet sémaphore initialisé pour lequel l’appelant fournit le stockage.
[in] Increment
Spécifie l’incrément de priorité à appliquer si la libération du sémaphore entraîne la satisfaction d’une attente.
[in] Adjustment
Spécifie une valeur à ajouter au nombre de sémaphores actuels. Cette valeur doit être positive.
[in] Wait
Spécifie si l’appel à KeReleaseSemaphore doit être suivi immédiatement par un appel à l’une des routines KeWaitXxx. Si TRUE, l’appel KeReleaseSemaphore doit être suivi d’un appel à KeWaitForMultipleObjects, KeWaitForMutexObjectou KeWaitForSingleObject. Pour plus d’informations, consultez la section Remarques suivante.
Valeur de retour
Si la valeur de retour est égale à zéro, l’état précédent de l’objet sémaphore n’est pas signalé.
Remarques
KeReleaseSemaphore fournit un boost de priorité au moment de l’exécution pour les threads en attente. Si cet appel définit le sémaphore à l’état signalé, le nombre de sémaphores est augmenté par la valeur spécifiée. L’appelant peut également spécifier s’il appelle l’une des routines KeWaitXxx dès que KeReleaseSemaphore retourne le contrôle.
La libération d’un objet sémaphore entraîne l’augmentation du nombre de sémaphores par la valeur du paramètre Ajustement. Si la valeur résultante est supérieure à la limite de l’objet sémaphore, le nombre n’est pas ajusté et une exception, STATUS_SEMAPHORE_LIMIT_EXCEEDED, est levée.
L’augmentation du nombre d’objets sémaphores entraîne l’atteinte d’un état signalé par le sémaphore, et une tentative est faite pour satisfaire autant d’attentes que possible sur l’objet sémaphore.
La routine KeReleaseSemaphore peut déclencher temporairement l’IRQL. Si le paramètre Wait est FALSE, la routine, avant de retourner, restaure le runtime d’intégration sur la valeur d’origine qu’il avait au début de l’appel.
Si Wait = TRUE, la routine retourne sans réduire le runtime d’intégration. Dans ce cas, l’appel KeReleaseSemaphore doit être immédiatement suivi d’un appel KeWaitXxx. En définissant Wait = TRUE, l’appelant peut empêcher un commutateur de contexte inutile de se produire entre l’appel KeReleaseSemaphore et l’appel KeWaitXxx. La routine KeWaitXxx, avant de retourner, restaure l’IRQL à sa valeur d’origine au début de l’appel KeReleaseSemaphore. Bien que l’IRQL désactive les commutateurs de contexte entre les deux appels, ces appels ne peuvent pas être utilisés de manière fiable comme début et fin d’une opération atomique. Par exemple, entre ces deux appels, un thread qui s’exécute en même temps sur un autre processeur peut modifier l’état de l’objet sémaphore ou de la cible de l’attente.
Avertissement
Un thread paginable ou une routine de pilote paginable qui s’exécute à IRQL = PASSIVE_LEVEL ne doit jamais appeler KeReleaseSemaphore avec le paramètre Wait défini sur TRUE. Un tel appel provoque une erreur de page irrécupérable si la fonction appelante est paginée entre les appels à KeReleaseSemaphore et KeWaitXxx.
Pour plus d’informations sur les objets sémaphores, consultez Objets sémaphores.
Les appelants de KeReleaseSemaphore doivent s’exécuter au <IRQL = DISPATCH_LEVEL à condition que Wait soit défini sur FALSE. Sinon, l’appelant doit s’exécuter à IRQL = PASSIVE_LEVEL.