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é (du 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 »  et  « récursif »,  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 « rapides » 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, l'état
       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 le thread 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)