Allocates a key and optionally associates a value with the key.
#include <nks/thread.h>
int NXKeyCreate (
void (*destructor)(void *value),
void *value,
NXKey_t *key);
(IN) Points to an application-specified destructor for destroying the value associated with the key. For an integer value, this can be NULL.
(IN) Points to the value to be associated with the allocated key in the context hosted by the calling thread. This can be NULL.
(OUT) Points to the allocated key.
If successful, returns 0; otherwise, returns a nonzero error code:
NXKeyCreate allocates a key in the virtual machine (VM) to which the calling thread belongs. Allocating a key reserves a slot in the context-specific data (CSD) array of all contexts that belong to the VM. Each currently created context is allocated a value slot, and any contexts created after the key is allocated a value slot. The calling thread that creates the key can set a value for the key at creation, but all other VM contexts have the key's value 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/context associated with it.
A key belongs to the virtual machine owning the threads that call NXKeyCreate. Its lifetime is independent of the context which created it. An allocated key remains allocated even if the context 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.
If a key is communicated outside the virtual machine (VM, which is equivalent to NLM™ on NetWare), it may not correspond in any useful way to its original function when data is stored or read by a thread in that different VM environment. Care must be taken to avoid communicating keys to another VM when a thread migrates into a foreign environment with knowledge of them.
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 contexts.
The destructor can be specified only when the key is created and cannot be subsequently changed.
Each context cannot set a different destructor for the same key.
The destructor must be able to handle a key value of zero. Because only some contexts might use a key and set its value, some contexts might exist with a zero value for the key.
The destructor is called when any context exits or is reinitialized. The value associated by the context 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 thread contexts in the VM, the specified value is associated with the allocated key only for the calling context. For example, if your VM has three threads, all three threads can use the same key, and each has its own unique value in the key. When you create the key, you can associate a value for the key, or you can pass NULL for the value parameter. The other contexts in the VM are automatically given a default value of NULL when the key is created. To set a key value, you use the NXKeySetValue function. For example:
extern void destructor( void * ); NXKey_t key; err = NXKeyCreate(destructor, NULL, &key); err = NXKeySetValue(key, 9);
For the calling thread, both of these operations could be done with one call:
err = NXKeyCreate(destructor, 9, &key);
Although a VM 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 CSD.
For sample code, see KeyValue.c.