Provided by: manpages-fr-extra_20151231_all 
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)