thr_keycreate(THREAD)

thr_keycreate -- create thread-specific data key

Synopsis

   cc [options] -Kthread file
   
   #include <thread.h>
   

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

Description

thr_keycreate creates a key visible to all threads in the process. The key plays the role of identifier for per-thread data. A thread can then bind a value to key with thr_setspecific(THREAD). Although the same key identifier can be used by different threads, the values bound to the key are maintained on a per-thread basis and persist for the life of the calling thread, or until explicitly replaced.

thr_keycreate sets the initial value of the key in all active and subsequently created threads to NULL. When thr_keycreate returns successfully the new key is stored in the location pointed to by key. The caller must ensure that creation and use of this key are synchronized (see Intro(SYNCH)).

Normally, the value bound to a key by a thread will be a pointer to dynamically allocated storage. When a thread terminates, per-thread context is automatically destroyed and, if a binding exists, the reference to the key is released. If the key has a destructor (see "key parameter"), the destructor is called with the bound value.

There is no fixed limit on the number of keys per process.

Parameters

key: pointer to the new thread-specific data key (set by thr_setspecific)
destructor: pointer to function to be called at thread exit, or NULL

key parameter

key points to the thread_key_t in which thr_keycreate will store the newly created key.

destructor parameter

destructor points to an optional destructor function to be associated with key. destructor can also be NULL. When a thread terminates, if it has a non-NULL destructor function and a non-NULL value associated with key, the destructor function will be called with the bound value as an argument. If the value associated with key is NULL, the destructor is not called. Destructors are intended to free any dynamically allocated storage associated with the bound value.

If destructor functions call thr_setspecific or thr_getspecific, it might not be possible to destroy all bindings for a terminating thread. The order in which the destructor functions are called is unspecified.

Return values

thr_keycreate returns zero for success and an error number for failure.

Errors

If any of the following conditions is detected, thr_keycreate returns the corresponding value:

ENOMEM: Insufficient memory exists to create the key.

Performance considerations

Although there is no fixed limit on the number of keys in a process, a large number of keys will consume memory and slow thread exit performance.

References

Intro(THREAD), Intro(SYNCH), mutex(SYNCH), thr_exit(THREAD), thr_getspecific(THREAD), thr_keydelete(THREAD), thr_setspecific(THREAD)

Examples

This example shows the use of thread-specific data in a function that can be called from more than one thread without special initialization. For the sake of simplicity, no error checking is done.

   static mutex_t keylock;
   static thread_key_t key;
   static int once = 0;
   
   void
   func()
   {
   	void *ptr;
   

   	(void) mutex_lock(&keylock);
   	if (!once) {
   		(void) thr_keycreate(&key, free);
   		once++;
   	}
   	(void) mutex_unlock(&keylock);
   	(void) thr_getspecific(key, (void *) &ptr);
   	if (ptr == NULL) {
   		ptr = malloc(SIZE);
   		(void) thr_setspecific(key, ptr);
   	}
   }