NOM
futex - Mécanisme de verrouillage rapide en mode utilisateur
SYNOPSIS
#include <linux/futex.h>
#include <sys/time.h>
int futex(int *uaddr, int op, int val, const struct timespec *timeout,
int *uaddr2, int val3);
L’appel système futex() donne à un programme la possibilité d’attendre
qu’une valeur à une adresse donnée change, ou de réveiller tous ceux
qui sont en attente sur cette adresse. Bien que les adresses soient
différentes dans des processus séparés, le noyau fera la correspondance
lors de l’appel système. Ceci est typiquement employé pour implémenter
les verrous en mémoire partagée, tels qu’ils sont décrits dans
futex(7).
Quand une opération futex(7) ne se termine pas de manière satisfaisante
dans l’espace utilisateur, un appel au noyau est nécessaire pour
l’arbitrage. Ceci signifie soit endormir le processus appelant, soit
réveiller le processus en attente.
Les appelants de cette fonction doivent accepter les sémantiques
décrites dans futex(7). Comme celles‐ci impliquent l’écriture
d’instructions non portables en assembleur, leurs utilisateurs sont des
auteurs de bibliothèques plus que des développeurs applicatifs.
Le paramètre uaddr doit pointer sur un entier aligné qui stocke le
compteur. L’opération à exécuter est transmise dans le paramètre op,
avec la valeur val.
Cinq opérations sont définies pour le moment :
FUTEX_WAIT
Cette opération vérifie que l’adresse du futex uaddr contient
toujours la valeur val indiquée et s’endort en attendant un
FUTEX_WAKE à cette adresse. Les deux étapes sont liées
atomiquement. Si l’argument timeout est non nul, il contient la
durée maximale de sommeil. Sinon, elle est infinie. Les
arguments uaddr2 et val3 sont ignorés.
D’après futex(7), cet appel est exécuté si la décrémentation du
compteur donne une valeur négative (indiquant un conflit) et le
sommeil durera jusqu’à ce qu’un autre processus relâche le futex
et exécute FUTEX_WAKE.
FUTEX_WAKE
Cette opération réveille au plus val processus en attente sur
l’adresse du futex (endormis dans FUTEX_WAIT). Les arguments
timeout, uaddr2 et val3 sont ignorés.
D’après futex(7), ceci est exécuté si l’incrémentation du
compteur montre qu’il y a des processus en attente, une fois que
la valeur du futex a été mise à 1 (indiquant qu’il est
disponible).
FUTEX_FD (présent jusqu’à Linux 2.6.25 inclus)
Pour permettre des réveils asynchrones, cette opération associe
un descripteur de fichier avec un futex. Si un autre processus
exécute un FUTEX_WAKE, l’appelant recevra le signal dont le
numéro a été indiqué dans val. L’appelant doit refermer le
descripteur de fichier après utilisation. Les arguments timeout,
uaddr2 et val3 sont ignorés.
Pour éviter les situations de concurrence, l’appelant doit
tester si le futex a été libéré après le retour de FUTEX_FD.
Parce qu’il était de façon inhérent sujet à des situations de
concurrence, FUTEX_FD a été supprimé de Linux 2.6.26 et les
suivants.
FUTEX_REQUEUE (depuis Linux 2.5.70)
Cette opération a été introduite dans le but d’éviter que trop
de processus nécessitant un autre futex ne soient activés lors
de l’utilisation de FUTEX_WAKE. Cet appel réactive val
processus, et remet en file d’attente tous les autres qui
attendaient le futex à l’adresse uaddr2. Les arguments timeout
et val3 sont ignorés.
FUTEX_CMP_REQUEUE (depuis Linux 2.6.7)
Il y a un problème de concurrence dans l’utilisation prévue pour
FUTEX_REQUEUE, aussi FUTEX_CMP_REQUEUE a été introduit. Cette
opération est similaire à FUTEX_REQUEUE, sauf qu’elle vérifie si
l’adresse uaddr contient encore la valeur val3. Si non,
l’opération échoue avec l’ erreur EAGAIN.L’argument timeout est
ignoré.
VALEUR RENVOYÉE
Suivant l’opération exécutée, la valeur renvoyée en cas de succès peut
avoir différentes significations.
FUTEX_WAIT
Renvoie 0 si le processus a été réveillé par un appel
FUTEX_WAKE. En cas de dépassement de délai, l’opération échoue
avec l’erreur ETIMEDOUT. L’opération échoue avec l’erreur
EWOULDBLOCK si le futex n’avait pas la valeur attendue.
L’arrivée d’un signal (voir signal(7)) ou un autre réveil
intempestif peut causer l’échec d’un FUTEX_WAIT avec l’erreur
EINTR.
FUTEX_WAKE
Renvoie le nombre de processus réveillés.
FUTEX_FD
Renvoie le nouveau descripteur associé au futex.
FUTEX_REQUEUE
Renvoie le nombre de processus réveillés.
FUTEX_CMP_REQUEUE
Renvoie le nombre de processus réveillés.
En cas d’erreur, toutes les opérations renvoient -1, et errno contient
le code d’erreur.
ERREURS
EACCES Pas d’accès en lecture à la mémoire futex.
EAGAIN FUTEX_CMP_REQUEUE a trouvé une valeur inattendue de futex. (Cela
indique probablement une condition de concurrence ; utilisez
maintenant FUTEX_WAKE.)
EFAULT Erreur lors de la récupération de l’information timeout à partir
de l’espace utilisateur.
EINVAL Une opération n’a pas été définie ou il y a une erreur
d’alignement de page.
ENFILE La limite du nombre total de fichiers ouverts sur le système a
été atteinte.
ENOSYS op contient une opération non valable.
VERSIONS
Le support initial des futex a été ajouté dans Linux 2.5.7 mais avec
une sémantique différente de celle décrite ci‐dessus. Un appel système
à 4 paramètres avec la sémantique expliquée ci‐dessus a été ajouté dans
Linux 2.5.40. Dans Linux 2.5.70, un paramètre supplémentaire a été
ajouté. Un sixième paramètre a été ajouté dans Linux 2.6.7 — compliqué,
surtout sur l’architecture s390.
CONFORMITÉ
Cet appel système est spécifique à Linux.
NOTES
Répétons‐le, les futex de base ne sont pas conçus comme une abstraction
facile à employer pour les utilisateurs (mais la glibc ne fournit pas
de fonction autour de cet appel système). Les implémenteurs doivent
maîtriser l’assembleur et avoir lu les sources de la bibliothèque en
espace utilisateur décrite ci-dessous.
VOIR AUSSI
futex(7)
« Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux »
(proceedings of the Ottawa Linux Symposium 2002), bibliothèque
d’exemple de futex, futex-*.tar.bz2
<URL:ftp://ftp.kernel.org:/pub/linux/kernel/people/rusty/>.
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Julien Cristau <jcristau@debian.org> et l’équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».