Sémaphores

Déclarations dans : be/kernel/OS.h

Librairie : libroot.so

Un sémaphore est un marqueur utilisé pour synchronizer plusieurs threads. Le concept du sémaphore est simple : pour entrer dans une "section critique" protogée par un sémaphore, un thread doit d'abord "aquérir" le sémaphore, par la fonction acquire_sem(). Lorsqu'il sort de la section critique, le thread "relâche" le sémaphore avec release_sem().

L'avantage du système de sémaphore est que si un thread ne peut pas acquérir un sémaphore (parce le sémaphore doit d'abord être relâché par le précédant acquéreur), le thread bloque dans l'appel à acquire_sem(). Pendant qu'il est bloqué, le thread ne gâche aucun cycle CPU.

Pour plus d'informations sur les sémaphores, consultez "Concepts de Sémaphore". Pour des exemples de code, consultez "Exemples d'usage de sémaphore".

Fonctions

acquire_sem() , acquire_sem_etc()

	status_t acquire_sem(sem_id sem) status_t acquire_sem_etc(sem_id sem,       uint32 count,       uint32 flags,       bigtime_t timeout)

Ces fonctions tentent d'acquérir le sémaphore identifié par l'argument sem. Sauf en cas d'erreur, acquire_sem() ne retourne pas tant que le sémaphore n'a pas été réellement acquis.

acquire_sem_etc() est la version véritable d'acquisition : c'est essentiellement la même que acquire_sem(), mais, en plus, elle vous laisse acquérir un sémaphore plus d'une fois, et fournir un mode timeout :

• L'argument count vous permet de spécifier le sémaphore que vous voulez acquérir count fois. Cela signifie que le compteur (on dit aussi compteur de thread) du sémaphore est décrémenté de ma quantité demandée. Il est illégal de passer un nombre inférieur à 1.

• Pour activer le timeout, vous ajoutez B_ABSOLUTE_TIMEOUT or B_RELATIVE_TIMEOUT à l'argument flags. timeout est le temps, en micro secondes, que vous voulez attendre, mesuré relativement à maintenant (timeout relatif) ou relatif à instant donné, tel qu'il est retourné par system_time() (timeout absolu). La fonction retourne B_TIMED_OUT si le sémaphore n'est pas acquis dans le temps imparti. Si vous passez un timeout de 0 et que le sémaphore n'est pas disponible immédiatement, la fonction retourne de suite B_WOULD_BLOCK.

Le kit du Noyau définit deux autres constantes de drapeau pour l'acquisition d'un sémaphore (B_CAN_INTERRUPT et B_CHECK_PERMISSION). Ces drapeaux additionnels sont utilisés par les pilotes de périphériques—ajouter ces drapeaux à l'acquisition "normale" (ou au niveau "applicatif" (user-level)) n'a pas d'effet. Malgré tout, vous devez savoir que le drapeau B_CHECK_PERMISSION est toujours ajouté lors d'une acquisition applicative afin de protéger les sémaphores globaux nécessaires au système.

A part le timeout et le nombre d'acquisition, il n'y a pas de différence entre les deux fonction d'acquisition. Spécifiquement, tout sémaphore peut être acquis par l'une ou l'autre fonction. Vous relâchez toujours un sémaphore par release_sem() (ou release_sem_etc()), peu importe quelle fonction fut utilisée pour l'acquérir.

Pour déterminer si un sémaphore est disponible, la fonction regarde le compteur du sémaphore (avant de le décrémenter) :

• Si le compteur est positif, le sémaphore est disponible et l'acquisition réussit. La fonction acquire_sem() (ou acquire_sem_etc()) retourne immédiatement après l'acquisition.

• Si le compteur est zéro ou moins, le thread appelant est placé dans la file de threads du sémaphore où il attendra qu'un appel à release_sem() le débloque (ou que le timeout expire).

CODES DE RETOUR

• B_NO_ERROR. Le sémaphore a été acquis avec succès.

• B_BAD_SEM_ID. L'argument sem n'identifie pas un sémaphore valide. Il est possible qu'un sémaphore devienne invalide pendant qu'un thread en acquisition attend dans sa file de thread.. Par exemple, si votre thread appelle acquire_sem() sur un sémaphore valide (mais indisponible), et qu'un autre thread détruit ce sémaphore, alors votre thread reviendra avec B_BAD_SEM_ID de son appel à acquire_sem().

• B_INTERRUPTED. L'acquisition à été interrompu par un signal. Dans ce cas, le sémaphore n'a pas été acquis.

Les autres valeurs de retour ne s'appliquent qu'à acquire_sem_etc() :

• B_BAD_VALUE. Valeur de count illégale (inférieur à 1).

• B_WOULD_BLOCK. Vous demandiez un timeout relatif de 0 et le sémaphore n'est pas disponible.

• B_TIMED_OUT. Le timeout est expiré (pour toute valeur de timeout autre que 0).

create_sem()

	sem_id create_sem(uint32 thread_count, const char *name)

Créé un nouveau sémaphore et retourne un sem_id unique au système qui l'identifie. Les arguments sont :

• thread_count initialize le compteur de thread du sémaphore, la variable compteur qui diminue et augmente selon que le sémaphore est acquis et relâché (respectivement). Vous pouvez passer tout nombre positif comme compteur, mais typiquement vous passerez 1 ou 0.

• name est le nom optionel que vous assignez au sémaphore. L'usage du nom est surtout le deboggage. Un nom de sémaphore n'a pas besoin d'être unique—plusieurs sémaphores peuvent avoir le même nom.

Les sem_id valides sont des entiers positifs. Vous devez toujours vérifier la validité d'un nouveau sémaphore via une séquence telle que :

   if ((my_sem = create_sem(1,"My Semaphore")) < B_OK)
      /* Si c'est moins que B_NO_ERROR, my_sem est invalide. */

create_sem() positionne le propriétaire du nouveau sémaphore à la team du thread appelant. La propriété peut être ré-affectée par la fonction set_sem_owner(). Lorsque le propriétaire meurt (lorsque tous les threads dans la team sont morts), le sémaphore est automatiquement détruit. Le propriétaire est aussi important dans un appel à delete_sem() : seuls les threads appartenant au propriétaire du sémaphore sont autorisés à détruire ce sémaphore.

CODES DE RETOUR

• B_BAD_VALUE. Valeur de thread_count invalide (inférieure à 0).

• B_NO_MEMORY. Pas assez de mémoire pour stocker le nom du sémaphore.

• B_NO_MORE_SEMS. Tous les sem_id valides sont utilisés.

delete_sem()

	status_t delete_sem(sem_id sem)

Détruit le sémaphore identifié par l'argument. S'il y a des threads attendant dans la file de threads du sémaphore, ils sont immédiatement débloqués.

Cette fonction ne peut être appellée que par un thread appartenant au propriétaire du sémaphore.

CODES DE RETOUR

• B_NO_ERROR. Le sémaphore à été détruit avec succès.

• B_BAD_SEM_ID. sem est invalide, ou le thread appelant n'appartient pas à la team qui possède le sémaphore.

get_sem_count()

	status_t get_sem_count(sem_id sem, int32 *thread_count)

Pour s'amuser uniquement; ne jamais déterminer le comportement de votre code sur cette fonction.

Retourne, par référence dans thread_count, la valeur du compteur de thread du sémaphore :

• Un compteur de thread positif (n) signifie qu'il n'y a pas de threads dans la file du sémaphore, et les n prochains appels à acquire_sem() retourneront sans bloquer.

• Si le compteur est zéro, il n'y a pas de threads en attente, mais le prochain appel à acquire_sem() bloquera.

• Un compteur négatif (-n) signifie qu'il y a n threads dans la file d'attente du sémaphore et que le prochain appel à acquire_sem() bloquera.

Pendant que cette fonction retourne et que vous observiez la valeur de thread_count, le compteur de thread du sémaphore peut avoir changé. Bien que l'observation du compteur de thread peut vous aider pendant le deboggage de votre programme, cette fonction ne doit pas être une partie complète de la conception de votre application.

CODES DE RETOUR

• B_NO_ERROR. Succès.

• B_BAD_SEM_ID. sem est invalide (thread_count n'est pas modifié).

get_sem_info() , get_next_sem_info()

	status_t get_sem_info(sem_id sem, sem_info *info) status_t get_next_sem_info(team_id team,       uint32 *cookie,       sem_info *info)

Copient les informations sur un sémaphore particulier dans la structure sem_info désignée par info. La première version de ces fonctions indique le sémaphore directement, par son sem_id.

La version get_next_sem_info(), elle, vous permet de parcourir la liste des sémaphores d'une team, par appel successifs. L'argument team identifie la team que vous voulez observer; une valeur team de 0 signifie la team du thread appelant. L'argument cookie est un marqueur, positionnez-le à 0 lors du premier appel, la fonction s'occupe du reste. Celle-ci retourne B_BAD_VALUE lorsqu'il n'y a plus de sémaphore à visiter :

   /* Obtenir le sem_info pour chaque sémaphore de cette team. */
   sem_info info;
   int32 cookie = 0;
   
   while (get_next_sem_info(0, &cookie, &info) == B_OK)
      ...

CODES DE RETOUR

• B_NO_ERROR. Succès.

• B_BAD_SEM_ID. Valeur de sem invalide.

• B_BAD_TEAM_ID. Valeur de team invalide.

release_sem() , release_sem_etc()

	status_t release_sem(sem_id sem) status_t release_sem_etc(sem_id sem, int32 count, uint32 flags)

La fonction release_sem() libère le thread qui attend en premier dans la file de threads du sémaphore (si il y en a un), et incrémente le compteur de thread du sémaphore. release_sem_etc() fait de même, mais pour count threads.

Normalement, relâcher un sémaphore invoque automatiquement le scheduler du noyau. Autrement dit, lorsque votre thread appelle release_sem(), vous êtes plutot sûr qu'un autre thread va être activé à votre place, même si votre thread n'avait pas reçu tout son quota de temps CPU. Si vous voulez éviter cet automatisme, appellez release_sem_etc() avec une valeur de flags à B_DO_NOT_RESCHEDULE. Prévenir la préemption automatique est particulièrement utile si vous relâcher tout un paquet de sémaphores d'un coup : en évitant la préemption vous évitez des changements de contexte non nécessaires.

CODES DE RETOUR

• B_NO_ERROR. Le sémaphore a été relâché avec succès.

• B_BAD_SEM_ID. Valeur de sem invalide.

• B_BAD_VALUE. Valeur de count invalide (inférieure à zéro; release_sem_etc() uniquement).

See also: acquire_sem()

set_sem_owner()

	status_t set_sem_owner(sem_id sem, team_id team)

Transfere la propriété d'un sémaphore particulier à team. Un sémaphore ne peut être la propriété que d'une seule team à la fois; en positionnant le propriétaire d'un sémaphore, vous le retirer à son propriétaire actuel.

Il n'y a pas des restrictions sur qui peut être propriétaire d'un sémaphore, ni sur qui peut transferer cette propriété. En pratique, cependant, la seule raison pour transferer la propriété est si vous écrivez un pilote de périphérique et que vous avez besoin qu'un sémaphore appartienne au noyau (la team connue, pour cet usage, comme B_SYSTEM_TEAM).

La propriété d'un sémaphore est nécessaire pour deux raisons :

• Lorsqu'une team meurt (lorsque ses threads sont tous morts), les sémaphores appartenant à cette team sont détruits.

• Les sémaphores ne peuvent être détruits que par les threads appartenant à la team propriétaire.

Pour découvrir le propriétaire d'un sémaphore, utilisez la fonction get_sem_info().

CODES DE RETOUR

• B_NO_ERROR. Succès.

• B_BAD_SEM_ID. Valeur de sem invalide.

• B_BAD_TEAM_ID. Valeur de team invalide.

Structures et Types

sem_id

	typedef int32 sem_id;

Les sem_id identifient les sémaphores. L'identifiant (id) est affecté lorsque le sémaphore est créé (create_sem()). Les valeurs sont uniques à travers tout le système.

sem_info

	typedef struct sem_info {       sem_id sem;       team_id team;       char name[B_OS_NAME_LENGTH];       int32 count;       thread_id latest_holder;       }

La structure sem_info fournit des informations sur un sémaphore. Vous obtenez cette structure par la fonction get_sem_info(). L'information dans la structure sem_info est garantie consistente en interne, mais l'ensemble de la structure doit être considérée comme non à jour dès que vous la recevez. Elle fournit une photo du sémaphore tel qu'il était juste avant le retour de la fonction.

Les champs sont :

• sem. Le sem_id du sémaphore.

• team. Le team_id du propriétaire du sémaphore.

• name. Le nom affecté au sémaphore.

• count. Le compteur de thread du sémaphore.

• latest_holder. Le plus récent thread qui a acquis le sémaphore.

Le champ lastest_holder est hautement non fiable; dans certains cas, le noyau n'enregistre même pas l'acquéreur du sémaphore. Bien que vous pouviez utiliser ce champ comme aide au deboguage, vous ne devriez pas trop le prendre au sérieux.

Constantes

Drapeaux de contrôle de sémaphore

• B_CAN_INTERRUPT Indique au noyau que l'on autorise l'interruption du sémaphore par un signal.

• B_DO_NOT_RESCHEDULE Indique au scheduler de ne pas intervenir lorsqu'un sémaphore est relâché, autrement dit, le thread qui vient de relâcher le sémaphore conserve son exécution, il n'est pas préempté.

• B_CHECK_PERMISSION S'assure que l'acquéreur/relâcheur du sémaphore fonctionne bien au bon niveau. C'est toujours ajouté dans les acquisitions/relâchements fait au niveau applicatif.

• B_RELATIVE_TIMEOUT Utilisé pour spécifier un timeout relatif à partir de maintenant.

• B_ABSOLUTE_TIMEOUT Utilisé pour spécifier un timeout relatif à l'horloge système.

• B_TIMEOUT     Obsolète; utilisez B_RELATIVE_TIMEOUT .