Provided by: manpages-fr-extra_20151231_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 *key, void (*destr_function) (void *));
int pthread_key_delete(pthread_key_t key);
int pthread_setspecific(pthread_key_t key, const void *pointer);
void * pthread_getspecific(pthread_key_t key);
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 POSIX sont la réponse à ce problème.
Chaque thread possède un segment mémoire privé, le TSD (Thread-Specific Data : Données Spécifiques au
Thread). Cette zone mémoire est indexée par des clés TSD. La zone TSD associe des valeurs du type void *
aux clés TSD. 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 TSD associe initialement NULL à toutes les clés.
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.
Le paramètre destr_function, si différent de NULL, spécifie une fonction de destruction 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 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
pointer à 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 argument clé.
pthread_getspecific() renvoie la valeur associée à clé en cas de succès et NULL en cas d'erreur.
ERREURS
pthread_key_create() renvoie le code d'erreur suivant :
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é TSD allouée valable.
pthread_getspecific() renvoie NULL si clé n'est pas une clef TSD allouée valable.
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é */
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
Cette page de manuel a été traduite par Thierry Vignaud <tvignaud AT mandriva DOT com> en 2000 et révisée
par Alain Portal <aportal AT univ-montp2 DOT fr> en 2006. La version présente dans Debian est maintenue
par les membres de la liste <debian-l10n-french AT lists DOT debian DOT org>. Veuillez signaler toute
erreur de traduction par un rapport de bogue sur le paquet manpages-fr-extra.
LinuxThreads PTHREAD_SPECIFIC(3)