Sous-routine pthread_key_create

Objectif

Crée une clé de données spécifique à l'unité d'exécution.

Bibliothèque

Bibliothèque d'unités d'exécution (libpthreads.a)

Syntaxe

#include <pthread.h>

int pthread_key_create ( key, destructor ) pthread_key_t * key; void (* destructor) (void *);

Descriptif

La sous-routine pthread_key_create crée une clé de données spécifique à l'unité d'exécution. La clé est partagée entre toutes les unités d'exécution du processus, mais chaque unité d'exécution possède des données spécifiques associées à la clé. Les données spécifiques à l'unité d'exécution sont un pointeur vide, initialement défini sur NULL.

L'application est chargée de s'assurer que cette sous-routine est appelée une seule fois pour chaque clé demandée. Cela peut être fait, par exemple, en appelant la sous-routine avant de créer d'autres unités d'exécution ou en utilisant la fonction d'initialisation à utilisation unique.

Généralement, les données spécifiques à l'unité d'exécution sont des pointeurs vers le stockage alloué de manière dynamique. Lors de la libération de la mémoire, la valeur doit être NULL. Il n'est pas recommandé de transtyper ce pointeur en type de données scalaires (int par exemple), car les transtypages peuvent ne pas être portables et la valeur de NULL dépend de l'implémentation.

Une routine de destructeur facultative peut être spécifiée. Elle est appelée pour chaque unité d'exécution lorsqu'elle est arrêtée et déconnectée, après l'appel aux routines de nettoyage, si la valeur spécifique n'est pas NULL. En règle générale, la routine de destructeur libère les données spécifiques à l'unité d'exécution de stockage. Il reçoit les données spécifiques à l'unité d'exécution en tant que paramètre.

Remarque: Le fichier d'en-tête pthread.h doit être le premier fichier inclus de chaque fichier source utilisant la bibliothèque d'unités d'exécution. Sinon, l'indicateur de compilation -D_THREAD_SAFE doit être utilisé ou le compilateur cc_r doit être utilisé. Dans ce cas, l'indicateur est automatiquement défini.

Paramètres

Article	Descriptif
key	Indique l'emplacement de stockage de la clé.
destructeur	Pointe vers une routine de destructeur facultative, utilisée pour nettoyer les données lors de l'arrêt de l'unité d'exécution. Si aucun nettoyage n'est souhaité, ce pointeur doit être NULL.

Valeurs renvoyées

Si l'opération aboutit, la fonction pthread_key_create stocke la valeur de clé nouvellement créée dans * key et renvoie zéro. Sinon, un numéro d'erreur est renvoyé pour indiquer l'erreur.

Codes d'erreur

La fonction pthread_key_create échoue si:

Article	Descriptif
FEAGA	Le système ne dispose pas des ressources nécessaires pour créer une autre clé de données spécifique à l'unité d'exécution ou la limite imposée par le système sur le nombre total de clés par processus PTHREAD_KEYS_MAX a été dépassée.
ENOMEM	La mémoire est insuffisante pour créer la clé.

La fonction pthread_key_create ne renvoie pas le code d'erreur EINTR.