ReleaseSemaphore, fonction (synchapi.h)

Article
03/04/2024

Augmente le nombre de l’objet sémaphore spécifié d’une quantité spécifiée.

Syntaxe

BOOL ReleaseSemaphore(
  [in]            HANDLE hSemaphore,
  [in]            LONG   lReleaseCount,
  [out, optional] LPLONG lpPreviousCount
);

Paramètres

[in] hSemaphore

Handle de l’objet sémaphore. La fonction CreateSemaphore ou OpenSemaphore retourne ce handle.

Ce handle doit avoir le droit d’accès SEMAPHORE_MODIFY_STATE . Pour plus d’informations, consultez Synchronisation des droits d’accès et de sécurité des objets.

[in] lReleaseCount

Quantité par laquelle le nombre actuel de l’objet sémaphore doit être augmenté. La valeur doit être supérieure à zéro. Si la quantité spécifiée entraîne le dépassement du nombre maximal spécifié lors de la création du sémaphore, le nombre n’est pas modifié et la fonction retourne FALSE.

[out, optional] lpPreviousCount

Pointeur vers une variable pour recevoir le nombre précédent du sémaphore. Ce paramètre peut être NULL si le nombre précédent n’est pas requis.

Valeur retournée

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étaillées sur l’erreur, appelez GetLastError.

Remarques

L’état d’un objet sémaphore est signalé lorsque son nombre est supérieur à zéro et non signé lorsque son nombre est égal à zéro. Le processus qui appelle la fonction CreateSemaphore spécifie le nombre initial du sémaphore. Chaque fois qu’un thread en attente est libéré en raison de l’état signalé du sémaphore, le nombre de sémaphores est réduit d’un.

En règle générale, une application utilise un sémaphore pour limiter le nombre de threads utilisant une ressource. Avant qu’un thread n’utilise la ressource, il spécifie le handle du sémaphore dans un appel à l’une des fonctions d’attente. Lorsque la fonction wait retourne, elle diminue le nombre de sémaphores d’un. Lorsque le thread a fini d’utiliser la ressource, il appelle ReleaseSemaphore pour augmenter le nombre de sémaphores d’un.

Une autre utilisation de ReleaseSemaphore est pendant l’initialisation d’une application. L’application peut créer un sémaphore avec un nombre initial de zéro. Cela définit l’état du sémaphore sur non signé et empêche tous les threads d’accéder à la ressource protégée. Lorsque l’application a terminé son initialisation, elle utilise ReleaseSemaphore pour augmenter le nombre à sa valeur maximale, afin de permettre un accès normal à la ressource protégée.

Il n’est pas possible de réduire le nombre d’objets sémaphores à l’aide de ReleaseSemaphore, car lReleaseCount ne peut pas être un nombre négatif. Pour restreindre ou réduire temporairement l’accès, créez une boucle dans laquelle vous appelez la fonction WaitForSingleObject avec un délai d’expiration de zéro jusqu’à ce que le nombre de sémaphores ait été suffisamment réduit. (Notez que d’autres threads peuvent réduire le nombre pendant l’exécution de cette boucle.) Pour restaurer l’accès, appelez ReleaseSemaphore avec le nombre de mises en production égal au nombre de fois où WaitForSingleObject a été appelé dans la boucle.

Exemples

Pour obtenir un exemple qui utilise ReleaseSemaphore, consultez Utilisation d’objets sémaphore.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	synchapi.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll