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é);  

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 comme 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 initialement 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, s'il n'est pas NULL, spécifie une fonction destructrice associée à une clé. Quand le thread se termine par pthread_exit(3) 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 destruction 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.  

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

EAGAIN

PTHREAD_KEYS_MAX clés sont déjà allouées.

pthread_key_delete() et pthread_setspecific() renvoient le code d'erreur suivant :

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.  

/* 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);
}

Ce document est une traduction réalisée par Thierry Vignaud <tvignaud AT mandriva DOT com> en 2000 et révisée le 19 novembre 2007.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 pthread_key_create ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.

NOM

SYNOPSIS

DESCRIPTION

VALEUR RENVOYÉE

ERREURS

EXEMPLE

AUTEUR

VOIR AUSSI

TRADUCTION