Provided by: manpages-fr-extra_20071013_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 il
       est très pratique pour protéger des données partagées de  modifications
       simultanées et pour implémenter des sections critiques et moniteurs.

       Un  mutex  peut  être  dans  deux  états : déverrouillé (pris par aucun
       thread) ou verrouillé (pris par 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 gère 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 ».
       Voyez   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 il 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 du mutex. Si ce dernier  est  de
       type  « rapide »,  le  thread  appelant  est suspendu jusqu’à ce que le
       mutex soit déverrouillé, plaçant ainsi 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’appels   à
       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, aucune ressource ne peut être associée à un mutex,  aussi
       pthread_mutex_destroy()  ne 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-jamais verrouiller un mutex pour de
       longues périodes de temps.

ASYNC-SIGNAL SAFETY

       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  de  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);
              /* operate on x */
              pthread_mutex_unlock(&mut);

TRADUCTION

       Cette page de manuel a été traduite par Thierry  Vignaud  <tvignaud  AT
       mandriva  DOT  com>  en  2000  et  révisée par Alain Portal <aportal AT
       univ-montp2 DOT fr> en 2006.   La  version  présente  dans  Debian  est
       maintenue  par les membres de la liste <debian-l10n-french AT lists DOT
       debian DOT org>.  Veuillez signaler toute erreur de traduction  par  un
       rapport de bogue sur le paquet manpages-fr-extra.

                                 LinuxThreads                 PTHREAD_MUTEX(3)