pthread_key_create (Subroutine)

Zweck

Erstellt einen threadspezifischen Datenschlüssel.

Bibliothek

Threadbibliothek (libpthreads.a)

Syntax

#include <pthread.h>

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

Beschreibung

Die Subroutine pthread_key_create erstellt einen threadspezifischen Datenschlüssel. Der Schlüssel wird von allen Threads innerhalb des Prozesses gemeinsam genutzt, aber jedem Thread sind bestimmte Daten zugeordnet. Die threadspezifischen Daten sind ein void-Zeiger, anfänglich auf NULLgesetzt.

Die Anwendung muss sicherstellen, dass diese Subroutine nur einmal für jeden angeforderten Schlüssel aufgerufen wird. Dies kann beispielsweise durch Aufrufen der Subroutine vor der Erstellung anderer Threads oder durch Verwendung der einmaligen Initialisierungsfunktion erfolgen.

In der Regel sind threadspezifische Daten Zeiger auf dynamisch zugeordneten Speicher. Beim Freigeben des Speichers sollte der Wert auf NULLgesetzt werden. Es wird nicht empfohlen, diesen Zeiger in einen skalaren Datentyp umzusetzen (z. B.int ), da die Umsetzungen möglicherweise nicht portierbar sind, und weil der Wert von NULL implementierungsabhängig ist.

Eine Destruktorroutine kann optional angegeben werden. Er wird für jeden Thread aufgerufen, wenn er beendet und freigegeben wird, nach dem Aufruf der Bereinigungsroutinen, wenn der spezifische Wert nicht NULList. Normalerweise gibt die Destruktorroutine die speicherthreadspezifischen Daten frei. Er empfängt die threadspezifischen Daten als Parameter.

Hinweis: Die Headerdatei pthread.h muss die erste eingeschlossene Datei jeder Quellendatei sein, die die Threadbibliothek verwendet. Andernfalls sollte das Kompilierungsflag -D_THREAD_SAFE oder der Compiler cc_r verwendet werden. In diesem Fall wird das Flag automatisch gesetzt.

Parameter

Element	Beschreibung
key	Zeigt an, wo der Schlüssel gespeichert wird.
Destruktor	Verweist auf eine optionale Destruktorroutine, die zum Bereinigen von Daten bei Threadbeendigung verwendet wird. Wenn keine Bereinigung gewünscht wird, sollte dieser Zeiger NULLsein.

Rückgabewerte

Bei erfolgreicher Ausführung speichert die Funktion pthread_key_create den neu erstellten Schlüsselwert bei * key und gibt null zurück. Andernfalls wird eine Fehlernummer zurückgegeben, die den Fehler angibt.

Fehlercodes

Die Funktion pthread_key_create schlägt in folgenden Fällen fehl:

Element	Beschreibung
EAGAIN	Dem System fehlten die erforderlichen Ressourcen für die Erstellung eines weiteren threadspezifischen Datenschlüssels oder der vom System festgelegte Grenzwert für die Gesamtzahl der Schlüssel pro Prozess PTHREAD_KEYS_MAX wurde überschritten.
ENOMEM	Nicht genügend Speicher zum Erstellen des Schlüssels vorhanden.

Die Funktion pthread_key_create gibt den Fehlercode EINTRnicht zurück.