1. What is Thread-Specific Data (TSD)?

2. When to Use TSD (vs Other Approaches)

3. Four Challenges TSD Must Solve

Before looking at the API, it helps to understand the four specific problems that TSD must solve for a library function:

4. The Thread-Specific Data API

4.1 pthread_key_create() — Create a Key

This function creates a new TSD key and stores it in *key. The key is a process-wide identifier (an index into an internal array) that all threads can use to store and retrieve their own private data.

The destructor argument is a pointer to a function that will be called automatically when a thread that has non-NULL data for this key terminates. The destructor receives the thread’s data pointer as its argument and is responsible for freeing it. If no cleanup is needed, pass NULL.

Because the key is used by all threads, key should point to a global or static variable. Key creation is typically done once using pthread_once().

/* Destructor function — called automatically when thread exits */
static void free_tsd_buffer(void *buf)
{
    free(buf);    /* buf is the value that was set with pthread_setspecific() */
    /* buf will not be NULL here — Pthreads only calls destructor if value != NULL */
}

/* One-time key creation */
static pthread_key_t my_key;
static pthread_once_t once = PTHREAD_ONCE_INIT;

static void create_key(void)
{
    int s = pthread_key_create(&my_key, free_tsd_buffer);
    if (s != 0) {
        fprintf(stderr, "pthread_key_create failed: %d\n", s);
        exit(1);
    }
}

4.2 pthread_setspecific() and pthread_getspecific()

These two functions form the core of the TSD API:

• pthread_setspecific(key, value) — Associates value (a pointer) with key for the calling thread. Only the calling thread’s association is modified; other threads’ associations for the same key are unaffected.
• pthread_getspecific(key) — Returns the pointer that was previously set for key in the calling thread. If this thread has never called pthread_setspecific() for this key, it returns NULL. This NULL return is how a function detects “first call from this thread.”

5. How TSD Is Implemented Internally (NPTL)

Understanding the internal implementation helps explain the API design. A typical implementation (like NPTL, the Linux Pthreads implementation) uses two data structures:

5.1 The Global Keys Array (pthread_keys[])

There is one process-wide array called pthread_keys[]. Each element represents one TSD key and contains:

• An “in use” flag — whether this slot has been allocated by pthread_key_create()
• A destructor pointer — the function to call when a thread with this key’s data exits

The value returned by pthread_key_create() is simply an index into this array.

5.2 Per-Thread TSD Pointer Arrays (tsd[])

Every thread also has its own private array called tsd[]. Each element corresponds to one key index from pthread_keys[]. It stores the pointer that was set by pthread_setspecific() for that key, in that thread.

When a thread is first created, all elements of its tsd[] array are initialized to NULL. This is why pthread_getspecific() returns NULL the first time a new thread calls it.

6. General Steps for Using TSD in a Library Function

7. Limits on TSD Keys

Because the key is an index into a fixed-size array, implementations impose a limit on how many keys can exist simultaneously. SUSv3 requires implementations to support at least 128 keys (_POSIX_THREAD_KEYS_MAX). Linux supports up to 1024 keys.

In practice, 128 keys is more than enough. Each well-written library function should use only one or a small number of keys. If a function needs multiple per-thread values, they should be packed into a single structure with one associated key.

/* Good practice: pack multiple per-thread values into one struct, use ONE key */
typedef struct {
    char error_buf[256];     /* Per-thread error string */
    int  last_error_code;    /* Per-thread error code */
    char temp_buffer[1024];  /* General-purpose per-thread scratch space */
} ThreadData;

/* One key for all per-thread data — conserves keys */
static pthread_key_t thread_data_key;
static pthread_once_t once = PTHREAD_ONCE_INIT;

static void free_thread_data(void *data) { free(data); }

static void create_thread_data_key(void) {
    pthread_key_create(&thread_data_key, free_thread_data);
}

static ThreadData *get_thread_data(void) {
    ThreadData *td;
    pthread_once(&once, create_thread_data_key);

    td = pthread_getspecific(thread_data_key);
    if (td == NULL) {
        td = calloc(1, sizeof(ThreadData));    /* allocate on first call */
        pthread_setspecific(thread_data_key, td);
    }
    return td;
}

/* Usage in library functions */
void my_lib_function_A(int err) {
    ThreadData *td = get_thread_data();
    strerror_r(err, td->error_buf, sizeof(td->error_buf));
    td->last_error_code = err;
}

void my_lib_function_B(const char *src) {
    ThreadData *td = get_thread_data();
    strncpy(td->temp_buffer, src, sizeof(td->temp_buffer) - 1);
    /* Use td->temp_buffer safely — it's per-thread */
}