Allocates a key for thread specific data.
#include <thread.h>
int thr_keycreate (
thread_key_t *key,
void (*destructor)(void *value));
(OUT) Points to the allocated key.
(IN) Points to an application-specified destructor for destroying the value associated with the key. For an integer value, this can be NULL.
If successful, returns 0; otherwise, returns a nonzero error code:
The thr_keycreate function allocates a key in the application to which the calling thread belongs. Allocating a key reserves a slot in the context-specific data (CSD) array of the application. Each currently created thread is allocated a value slot, and any thread created after the key is allocated a value slot. The key's value is initialized to zero. Once a key is allocated, it is accessible anywhere, and the value in the slot corresponding to the key in question can be changed by the thread associated with it.
A key belongs to the application owning the threads that call thr_keycreate. Its lifetime is independent of the thread which created it. An allocated key remains allocated even if the thread which originally created the key exits. Each thread must set its own value for the key, and that value is destroyed when the thread exits.
An optional destructor function can be specified for an allocated key. This destructor permanently corresponds to the allocated key until the key is deleted:
The destructor applies across all threads.
The destructor can be specified only when the key is created and cannot be subsequently changed.
Each thread cannot set a different destructor for the same key.
The destructor must be able to handle a key value of zero. Because only some threads might use a key and set its value, some threads might exist with a zero value for the key.
The destructor is called when any thread exits. The value associated by the thread is passed as a parameter to the destructor.
The destructor function must correspond to the type of data stored in the value parameter:
If you are storing an integer in the value parameter, pass NULL for the destructor. The value parameter doesn't have to be a pointer because an integer value can be stored within the key structure.
If you are storing a pointer to a string in the value parameter and you used malloc for the string's memory, use the free function for the destructor.
If the value is a pointer to complicated data structure, use a developer created function that can walk the structure and free all its memory.
While the allocated key applies across all threads in the application, the specified value is associated with the allocated key only for the calling thread. For example, if your application has three threads, all three threads can use the same key, and each has its own unique value in the key. To set a key value, you use the thr_setspecific function.
Although an application can support up to 64 (NX_MAX_KEYS) keys, you seldom need to use more than one because you can store a heap-allocated structure with all the per-thread data your application needs, all with one key.
See Section 52.3, Context-Specific Data for more information about how CSD has been implemented on NetWare.