Provided by: manpages-fr_1.67.0-1_all bug

NOM

       pthread_mutex_init,      pthread_mutex_lock,     pthread_mutex_trylock,
       pthread_mutex_unlock, pthread_mutex_destroy - opérations sur les mutex

SYNOPSIS

       #include <pthread.h>

       pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER;

       pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;

       pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;

       int       pthread_mutex_init(pthread_mutex_t       *mutex,        const
       pthread_mutexattr_t *mutexattr);

       int pthread_mutex_lock(pthread_mutex_t *mutex));

       int pthread_mutex_trylock(pthread_mutex_t *mutex);

       int pthread_mutex_unlock(pthread_mutex_t *mutex);

       int pthread_mutex_destroy(pthread_mutex_t *mutex);

DESCRIPTION

       Un  mutex  est un objet d’exclusion mutuelle (MUTual EXclusion), et est
       très pratique pour protéger  des  données  partagées  de  modifications
       concurrentes et pour implémenter des sections critiques.

       Un  mutex  peut  ête  dans  deux  états  : déverrouillé (pris par aucun
       thread) ou verrouillé (appartenant à un thread). Un mutex ne peut  être
       pris  que  par  un  seul  thread  à  la  fois.  Un  thread qui tente de
       verrouiller un mutex déjà verrouillé est suspendu  jusqu’à  ce  que  le
       mutex soit déverrouillé.

       pthread_mutex_init  initialise  le  mutex  pointé  par  mutex selon les
       attributs de mutex spécifié par mutexattr.  Si mutexattr vaut NULL, les
       paramètres par défaut sont utilisés.

       L’implémentation  LinuxThreads ne supporte qu’un seul attribut, le type
       de  mutex,  qui  peut  être  soit   ‘‘rapide’’,   ‘‘récursif’’   ou   à
       ‘‘vérification  d’erreur’’.  Le  type de mutex détermine s’il peut être
       verrouillé plusieurs fois par le même thread. Le type  par  défaut  est
       ‘‘rapide’’. Voir pthread_mutexattr_init(3) pour plus d’informations sur
       les attributs de mutex.

       Les variables de type pthread_mutex_t peuvent aussi  être  initialisées
       de     manière     statique,     en     utilisant     les    constantes
       PTHREAD_MUTEX_INITIALIZER      (pour      les      mutex      rapides),
       PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP  (pour  les mutex récursifs), et
       PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP (pour les mutex à  vérification
       d’erreur).

       pthread_mutex_lock  verrouille  le mutex. Si le mutex est déverrouillé,
       il devient verrouillé et  est  possédé  par  le  thread  appelant ;  et
       pthread_mutex_lock  rend  la  main  immédiatement. Si le mutex est déjà
       verrouillé par un autre thread, pthread_mutex_lock  suspend  le  thread
       appelant jusqu’à ce que le mutex soit déverrouillé.

       Si le mutex est déjà verrouillé par le thread appelant, le comportement
       de pthread_mutex_lock dépend du type de mutex. Si  ce  dernier  est  de
       type  ‘‘rapide’’,  le  thread  appelant  est suspendu jusqu’à ce que le
       mutex soit déverrouillé, donc plaçant le thread appelant  en  situation
       de  blocage  définitif.  Si  le  mutex  est  de  type  ‘‘à vérification
       d’erreur’’, pthread_mutex_lock rend la main immédiatement avec le  code
       d’erreur   EDEADLK.    Si   le   mutex   est   de   type  ‘‘récursif’’,
       pthread_mutex_lock rend la main immédiatement avec un  code  de  retour
       indiquant  le  succès,  enregistrant  le  nombre  de  fois où le thread
       appelant  a  verrouillé  le   mutex.   Un   nombre   égal   d’appel   à
       pthread_mutex_unlock  doit  être  réalisé avant que le mutex retourne à
       l’état déverrouillé.

       pthread_mutex_trylock   se   comporte   de   la   même   manière    que
       pthread_mutex_lock, excepté qu’elle ne bloque pas le thread appelant si
       le mutex est déjà verrouillé par un autre  thread  (ou  par  le  thread
       appelant   dans   le   cas   d’un   mutex  ‘‘rapide’’).  Au  contraire,
       pthread_mutex_trylock rend la main immédiatement avec le code  d’erreur
       EBUSY.

       pthread_mutex_unlock   déverrouille  le  mutex.  Celui-ci  est  supposé
       verrouillé,  et  ce   par   le   thread   courant   en   entrant   dans
       pthread_mutex_unlock.    Si   le   mutex   est   de   type  ‘‘rapide’’,
       pthread_mutex_unlock le réinitialise toujours  à  l’état  déverrouillé.
       S’il  est  de  type  ‘‘récursif’’,  son  compteur  de  verrouillage est
       décrémenté (nombre d’opérations  pthread_mutex_lock  réalisées  sur  le
       mutex  par  le  thread  appelant),  et  déverrouillé seulement quand ce
       compteur atteint 0.

       Sur les mutex ‘‘vérification d’erreur’’,  pthread_mutex_unlock  vérifie
       lors  de  l’exécution  que le mutex est verrouillé en entrant, et qu’il
       est   verrouillé   par   le   même   thread    que    celui    appelant
       pthread_mutex_unlock.   Si  ces conditions ne sont pas réunies, un code
       d’erreur  est  renvoyé  et  le  mutex  n’est  pas  modifié.  Les  mutex
       ‘‘rapide’’ et ‘‘récursif’’ ne réalisent pas de tels tests, permettant à
       un mutex verrouillé d’être déverrouillé par un thread autre  que  celui
       l’ayant  verrouillé. Ce comportement n’est pas portable et l’on ne doit
       pas compter dessus.

       pthread_mutex_destroy détruit un mutex, libérant les  ressources  qu’il
       détient.   Le  mutex  doit  être  déverrouillé.  Dans  l’implémentation
       LinuxThreads des threads POSIX, aucune ressource ne peut être associé à
       un  mutex, aussi pthread_mutex_destroy ne fait en fait rien si ce n’est
       vérifier que le mutex n’est pas verrouillé.

ANNULATION

       Aucune des primitives relatives aux mutex n’est un point  d’annulation,
       ni  même  pthread_mutex_lock,  malgré  le  fait  qu’il  peut  suspendre
       l’exécution du thread pour une  longue  durée.  De  cette  manière,  le
       statut des mutex aux points d’annulation est prévisible, permettant aux
       gestionnaires d’annulation de déverrouiller précisément ces  mutex  qui
       nécessitent  d’être  déverrouillés  avant  que l’exécution du thread ne
       s’arrête  définitivement.  Aussi,  les  threads  travaillant  en   mode
       d’annulation retardée ne doivent-t’ils jamais verrouiller un mutex pour
       de longues périodes de temps.

FIABILITE PAR RAPPORT AUX SIGNAUX ASYNCHRONES

       Les fonctions relatives aux mutex ne sont pas fiables par  rapport  aux
       signaux  asynchrones  et  ne  doivent  donc pas être utilisées dans des
       gestionnaires de signaux. En particulier, appeler pthread_mutex_lock ou
       pthread_mutex_unlock  dans  un  gestionnaire  de  signal peut placer le
       thread appelant dans une situation de blocage définitif.

VALEUR RENVOYÉE

       pthread_mutex_init retourne toujours 0. Les autres fonctions  renvoient
       0 en cas succès et un code d’erreur non nul en cas de problème.

ERREURS

       La fonction pthread_mutex_lock renvoie l’un des codes d’erreur suivants
       en cas de problème:

              EINVAL le mutex n’a pas été initialisé.

              EDEADLK
                     le mutex est déjà verrouillé  par  un  thread  autre  que
                     l’appelant (mutex à vérification d’erreur seulement).

       La  fonction  pthread_mutex_trylock  renvoie  l’un  des  codes d’erreur
       suivants en cas de problème :

              EBUSY  le mutex ne peut être verrouillé car il l’est déjà.

              EINVAL le mutex n’a pas été initialisé.

       La fonction pthread_mutex_unlock renvoie le code  d’erreur  suivant  en
       cas de problème :

              EINVAL le mutex n’a pas été initialisé.

              EPERM  le  thread  appelant  ne  possède  pas  le mutex (mutex à
                     vérification d’erreur seulement).

       La fonction pthread_mutex_destroy renvoie le code d’erreur  suivant  en
       cas de problème :

              EBUSY  le mutex est déjà verrouillé.

AUTEUR

       Xavier Leroy <Xavier.Leroy@inria.fr>

VOIR AUSSI

       pthread_mutexattr_init(3),             pthread_mutexattr_setkind_np(3),
       pthread_cancel(3).

EXEMPLE

       Une variable globale partagée x peut être protégée par un  mutex  comme
       suit :

              int x;
              pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;

       Tous  les  accès  et modifications de x doivent être entourés de paires
       d’appels à pthread_mutex_lock et pthread_mutex_unlock comme suit :

              pthread_mutex_lock(&mut);
              /* agir sur x */
              pthread_mutex_unlock(&mut);

TRADUCTION

       Thierry Vignaud <tvignaud@mandrakesoft.com>, 2000
       Christophe Blaess, 2003.