Copyright Digital Equipment Corp. All rights reserved.
This routine generates a unique, thread-specific data key that is visible to all threads in the process. The variable key provided by this routine is an opaque object used to locate thread-specific data. Although the same key value can be used by different threads, the values bound to the key by pthread_ setspecific() are maintained on a per-thread basis and persist for the life of the calling thread. The initial value of the key in all threads is NULL. The Threads Library imposes a maximum number of thread-specific data keys, equal to the symbolic constant PTHREAD_KEYS_MAX. Thread-specific data allows client software to associate "static" information with the current thread. For example, where a routine declares a variable static in a single-threaded program, a multithreaded version of the program might create a thread- specific data key to store the same variable. This routine generates and returns a new key value. The key reserves a cell within each thread. Each call to this routine creates a new cell that is unique within an application invocation. Keys must be generated from initialization code that is guaranteed to be called only once within each process. (See the pthread_once() description for more information.) When a thread terminates, its thread-specific data is automatically destroyed; however, the key remains unless destroyed by a call to pthread_key_delete(). An optional destructor function can be associated with each key. At thread exit, if a key has a non-NULL destructor pointer, and the thread has a non-NULL value associated with that key, the destructor function is called with the current associated value as its sole a