Provided by: manpages-fr_1.67.0-1_all bug

NOM

       pthread_key_create,       pthread_key_delete,      pthread_setspecific,
       pthread_getspecific - gestion de données spécifiques à un thread

SYNOPSIS

       #include <pthread.h>

       int pthread_key_create(pthread_key_t *cl, void (*destr_function) (void
       *));

       int pthread_key_delete(pthread_key_t cl);

       int pthread_setspecific(pthread_key_t cl, const void *pointeur);

       void * pthread_getspecific(pthread_key_t cl);

DESCRIPTION

       Les  programmes  ont  souvent besoin de variables globales ou statiques
       ayant différentes  valeurs  dans  des  threads  différents.  Comme  les
       threads  partagent  le  même  espace mémoire, cet objectif ne peut être
       réalisé avec les variables  usuelles.  Les  données  spécifiques  à  un
       thread de POSIX sont la réponse à ce problème.

       Chaque  thread possède un segment mémoire privé, le TSD (Thred-Specific
       Data : Données Spécifiques au Thread). Cette zone mémoire  est  indexée
       par  des  clés  TSD. La zone TST associe des valeurs du type void * aux
       clés TST. Ces clés sont communes à tous les  threads,  mais  la  valeur
       associée à une clé donnée est différente dans chaque thread.

       Pour  concrétiser ce formalisme, les zones TSD peuvent être vues commes
       des tableaux de pointeurs void  *,  les  clés  TSD  comme  des  indices
       entiers  pour  ces  tableaux,  et  les  valeurs  des clés TSD comme les
       valeurs des entrées correspondantes dans le tableau du thread appelant.

       Quand  un  thread  est  créé, sa zone TST est unitialement associée aux
       clés NULL.

       pthread_key_create  alloue  une  nouvelle  clé  TSD.  Cette   clé   est
       enregistrée  à  l’emplacement pointée par cl.  Il ne peut y avoir plus
       de PTHREAD_KEYS_MAX  clés  allouées  à  un  instant  donné.  La  valeur
       initialement  associée  avec  la  clé  renvoyée  est NULL dans tous les
       threads en cours d’exécution.

       L’argument destr_function, si différent de NULL, spécifie une  fonction
       destructrice  associée  à  une  clé.  Quand  le  thread  se termine par
       pthread_exit ou par une annulation, destr_function est appelée avec  en
       argument  les  valeurs  associées  aux  clés  de ce thread. La fonction
       destr_function n’est pas appelée si cette  valeur  est  NULL.   L’ordre
       dans  lequel les fonctions de desctruction sont appelées lors de la fin
       du thread n’est pas spécifiée.

       Avant que la fonction de destruction soit appelée, la valeur  NULL  est
       associée  à  la clé dans le thread courant. Une fonction de destruction
       peut cependant réassocier une valeur différente de NULL à cette clé  ou
       une  autre  clé.  Pour gérer ce cas de figure, si après l’appel de tous
       les destructeurs pour  les  valeurs  différentes  de  NULL,  il  existe
       toujours   des  valeurs  différentes  de  NULL  avec  des  destructeurs
       associés,  alors  la  procédure  est  répétée.    L’implémentation   de
       LinuxThreads        interrompt        cette       procédure       après
       PTHREAD_DESTRUCTOR_ITERATIONS itérations, même s’il reste  des  valeurs
       différentes   de   NULL   associées  à  des  descripteurs.  Les  autres
       implémentations peuvent boucler sans fin.

       pthread_key_delete désalloue une clé TSD. Elle ne vérifie  pas  si  des
       valeurs  différentes  de  NULL  sont  associées avec cette clé dans les
       threads en cours d’exécution, ni n’appelle la fonction  de  destruction
       associée avec cette clé.

       pthread_setspecific  change  la valeur associée avec cl dans le thread
       appelant, sauve le paramètre pointeur à sa place.

       pthread_getspecific renvoie la valeur actuellement  associée  avec  cl
       dans le thread appelant.

VALEUR RENVOYÉE

       pthread_key_create,    pthread_key_delete,    et    pthread_setspecific
       renvoient 0 en cas de succès  et  un  code  d’erreur  non  nul  en  cas
       d’échec.  En  cas  de  succès,  pthread_key_create  enregistre  la  clé
       récemment créée à l’emplacement pointé par son arguement cl.

       pthread_getspecific renvoie la valeur associée à cl en cas  de  succès
       et NULL en cas d’erreur.

ERREURS

       pthread_key_create renvoient l’un des codes d’erreur suivants :

              EAGAIN PTHREAD_KEYS_MAX les clés sont déjà allouées

       pthread_key_delete  et  pthread_setspecific  renvoient  l’un  des codes
       d’erreur suivants :

              EINVAL cl n’est pas une clé valide ou allouée

       pthread_getspecific renvoie NULL si la cl n’est  pas  associée  à  des
       données spécifiques.

AUTEUR

       Xavier Leroy <Xavier.Leroy@inria.fr>

VOIR AUSSI

       pthread_create(3), pthread_exit(3), pthread_testcancel(3).

EXEMPLE

       L’extrait  de  code  suivant  alloue  dans  un thread un tableau de 100
       caractères, avec libération de la mémoire automatiquement à la  fin  de
       l’exécution du thread.

              /* Clé pour le tampon spécifique au thread */
              static pthread_key_t buffer_key;

              /* Initialisation unique de la clé */
              static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;

              /* Alloue le tampon spécifique au thread */
              void buffer_alloc(void)
              {
                pthread_once(&buffer_key_once, buffer_key_alloc);
                pthread_setspecific(buffer_key, malloc(100));
              }

              /* Renvoie le tampon spécifique au thread */
              char * get_buffer(void)
              {
                return (char *) pthread_getspecific(buffer_key);
              }

              /* Alloue la clée */
              static void buffer_key_alloc()
              {
                pthread_key_create(&buffer_key, buffer_destroy);
              }

              /* Libère le tampon spécifique au thread */
              static void buffer_destroy(void * buf)
              {
                free(buf);
              }

TRADUCTION

       Thierry Vignaud <tvignaud@mandrakesoft.com>, 2000
       Christophe Blaess, 2003.