1. NOM▲

futex - Verrouillage rapide en mode utilisateur

2. SYNOPSIS ▲

 
Sélectionnez
#include <linux/futex.h>
#include <sys/time.h>
int futex(int *uaddr, int op, int val, const struct timespec *timeout,
          int *uaddr2, int val3);

3. DESCRIPTION ▲

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. Cet appel système 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(hyci 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 minimale 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é.

4. VALEUR RENVOYÉE ▲

En cas d'erreur, toutes les opérations renvoient -1, et errno contient le code d'erreur. La valeur de retour en cas de succès dépend de l'opération, conformément à la description de la liste suivante.

  • FUTEX_WAIT
        Renvoie O si le processus a été réveillé par un appel FUTEX_WAKE. Consultez ERREURS pour les divers retours d'erreur possibles.
  • 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.

5. ERREURS ▲

  • EACCES
        Pas d'accès en lecture à la mémoire futex.
  • EAGAIN
        FUTEX_CMP_REQUEUE a détecté que la valeur pointée par uaddr n'est pas égale à la valeur val3 attendue (cela indique probablement une situation de compétition ; utilisez maintenant FUTEX_WAKE).
  • EFAULT
        Erreur de récupération du renseignement timeout depuis l'espace utilisateur.
  • EINTR
        Une opération FUTEX_WAIT a été interrompue par un signal (consultez signal(7)) ou un réveil involontaire.
  • EINVAL
        Argument incorrect.
  • ENFILE
        La limite du nombre total de fichiers ouverts sur le système a été atteinte.
  • ENOSYS
        op contient une opération non valable.
  • ETIMEDOUT
        Temps d'attente atteint pendant l'opération FUTEX_WAIT.
  • EWOULDBLOCK
        op était FUTEX_WAIT et la valeur pointée par uaddr n'était pas égale à la valeur val attendue au moment de l'appel.

6. 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(hydessus. Un appel système à 4 paramètres avec la sémantique décrite dans cette page 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.

7. CONFORMITÉ ▲

Cet appel système est spécifique à Linux.

8. NOTES ▲

Répétons(hyle, 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.

9. VOIR AUSSI ▲

futex(7)

« Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux » (proceedings of the Ottawa Linux Symposium 2002), disponible en ligne à
http://kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf

La bibliothèque d'exemple de futex, futex-*.tar.bz2 à
ftp://ftp.nl.kernel.org/pub/linux/kernel/people/rusty/

10. COLOPHON ▲

Cette page fait partie de la publication 3.52 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/.

11. TRADUCTION ▲

Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal <http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».