Multithreaded Programming Guide

Creating a Key for Thread-Specific Data

Single-threaded C programs have two basic classes of data: local data and global data. For multithreaded C programs a third class, thread-specific data, is added. Thread-specific data is very much like global data, except that the data is private to a thread.


Note –

The Solaris OS supports an alternative facility that allows a thread to have a private copy of a global variable. This mechanism is referred to as thread local storage (TLS). The keyword __thread is used to declare variables to be thread-local, and the compiler automatically arranges for these variables to be allocated on a per-thread basis. See Chapter 8, Thread-Local Storage, in Linker and Libraries Guide for more information.


Thread-specific data (TSD) is maintained on a per-thread basis. TSD is the only way to define and refer to data that is private to a thread. Each thread-specific data item is associated with a key that is global to all threads in the process. By using the key, a thread can access a pointer ( void *) maintained per-thread.

pthread_key_create Syntax

int pthread_key_create(pthread_key_t *key,
    void (*destructor) (void *));
#include <pthread.h>

pthread_key_t key;
int ret;

/* key create without destructor */
ret = pthread_key_create(&key, NULL);

/* key create with destructor */
ret = pthread_key_create(&key, destructor); 

Use pthread_key_create(3C) to allocate a key that is used to identify thread-specific data in a process. The key is global to all threads in the process. When the thread-specific data is created, all threads initially have the value NULL associated with the key.

Call pthread_key_create() once for each key before using the key. No implicit synchronization exists for the keys shared by all threads in a process.

Once a key has been created, each thread can bind a value to the key. The values are specific to the threads and are maintained for each thread independently. The per-thread binding is deallocated when a thread terminates if the key was created with a destructor function.

When pthread_key_create() returns successfully, the allocated key is stored in the location pointed to by key. The caller must ensure that the storage and access to this key are properly synchronized.

An optional destructor function, destructor, can be used to free stale storage. If a key has a non-NULL destructor function and the thread has a non-NULL value associated with that key, the destructor function is called with the current associated value when the thread exits. The order in which the destructor functions are called is unspecified.

pthread_key_create Return Values

pthread_key_create() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occur, pthread_key_create() fails and returns the corresponding value.


EAGAIN

Description:

The key name space is exhausted.


ENOMEM

Description:

Insufficient virtual memory is available in this process to create a new key.