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 une attente.

[in] Adjustment

Spécifie une valeur à ajouter au nombre actuel de sémaphores. Cette valeur doit être positive.

[in] Wait

Spécifie si l’appel à KeReleaseSemaphore doit être suivi immédiatement d’un appel à l’une des routines KeWaitXxx . Si la valeur est TRUE, l’appel KeReleaseSemaphore doit être suivi d’un appel à KeWaitForMultipleObjects, KeWaitForMutexObject ou KeWaitForSingleObject. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

Si la valeur de retour est zéro, l’état précédent de l’objet sémaphore n’est pas signalé.

Remarques

KeReleaseSemaphore fournit une augmentation de la priorité d’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é de 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 Adjustment . 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 effectuée pour satisfaire autant d’attentes que possible sur l’objet sémaphore.

La routine KeReleaseSemaphore peut temporairement déclencher l’IRQL. Si le paramètre Wait a la valeur FALSE, la routine, avant qu’elle ne retourne, restaure l’IRQL à la valeur d’origine qu’elle avait au début de l’appel.

Si l’argument Wait = TRUE est attendu, la routine retourne sans abaisser l’IRQL. 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 changement 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 être en cours d’exécution sur IRQL <= DISPATCH_LEVEL à condition que Wait ait la valeur FALSE. Sinon, l’appelant doit être en cours d’exécution à IRQL = PASSIVE_LEVEL.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Consultez la section Notes.
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport)

Voir aussi

KeInitializeSemaphore

KeReadStateSemaphore

KeWaitForMultipleObjects

KeWaitForSingleObject