Provided by:
manpages-fr_1.67.0-1_all 
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.