Threads

Thread-specific data

Historically, programs have used the static or extern storage classes to save data that must be preserved between function calls. This practice is no longer valid when many threads in the same process may run a given function concurrently and reference one static or extern variable by name. Values will not be preserved across function calls if one thread modifies a value left by another.

NOTE: In contrast, since each thread gets a unique stack, variables of the auto storage class are implicitly unique.

The facility for ``thread-specific'' data provides a solution to this problem.

Data can be stored and retrieved by a ``key'' value.
The same key value can be used to store data by many threads.
Implicit in the access functions [thr_setspecific(3thread) and thr_getspecific(3thread)] is a disambiguation of the key by the thread ID.
Thus, the key is a ``virtual variable name'' that will resolve to the correct data for the calling thread.
NOTE: Analogously, the file name /dev/tty can be used by any process to access its particular controlling terminal.
The data is specific to each thread but, as with any other part of the process address space, the data is not protected from access or change by other threads.

The access functions have the following syntax:

   int  thr_setspecific(thread_key_t key, void *data);
   int  thr_getspecific(thread_key_t key; void **value);

A key value must be created by the thr_keycreate(3thread) function

   int thr_keycreate(
   	thread_key_t *key,
   	void         (*destructor)(void *data)
   );

where

key: This is the address where the newly valid key value will be deposited.
destructor: specifies a function that will be called on the exit of any thread that has used the key for data storage. This function should recover any space that has been used to store thread-specific data. When called, this function receives one argument, the data address that the thread gave as the second argument to thr_setspecific(3thread).

NOTE: The key can be created (or later removed) by threads other than those that use the key for data storage. The using threads need only have access to the key value by function argument, global variable, or other means.

If a particular key value is needed for only a particular phase of a program (perhaps initialization) it can be deallocated by thr_keydelete(3thread).

For efficiency, it is best to minimize the number of keys used in an application.