NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO
$(OS_DIR)/lib/libpthreads.a #include <pthread.h>int pthread_key_create(pthread_key_t * key, void (* destructor ) void *);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
The pthread_key_create() function dynamically creates a unique thread-specific data key visible to all threads in the current actor, and stores it at the location referenced by key . Key values returned by pthread_key_create() are opaque indices used to locate thread-specific data. Although the same key value will 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.
On key creation, the value NULL is associated with the new key in all active threads. On thread creation, the value NULL is associated with all defined keys in the new thread.
An optional destructor function may be associated with each key value. At thread exit, if any key value has a non-NULL destructor pointer, and the thread has a non-NULL value associated with that key, the function destructor() is called with the value currently associated to it as its sole argument. After the destructor function returns, the value associated with the key in the current thread is reset to NULL. The order of destructor calls is unspecified if there is more than one destructor function for a thread when it exits.
If a destructor creates thread-specific data (by invoking pthread_setspecific() ), the destructor call can be repeated as many as PTHREAD_DESTRUCTOR_ITERATIONS times, to process all the thread-specific data. After PTHREAD_DESTRUCTOR_ITERATIONS iterations, destructor processing will terminate for the thread, even if more non-NULL thread-specific data remains.
The pthread_key_delete() function deletes a thread-specific data key. Any attempt to use key in any thread following the call to pthread_key_delete() results in undefined behavior. No destructor functions are invoked by pthread_key_delete() . The application must free storage and perform any cleanup operations needed for data structures related to the deleted key or to associated thread-specific data. The cleanup can be performed before or after invoking pthread_key_delete() .
At actor destruction, all remaining keys associated with the actor are silently deleted. No destructor functions are invoked.
On successful completion, pthread_key_create() and pthread_key_delete() return zero. Otherwise, an error code is returned.
These functions do not set errno .
The key value is invalid ( pthread_key_delete() only).
The system-imposed limit on the total number of keys per actor (PTHREADS_KEYS_MAX) has been exceeded ( pthread_key_create() only).
There is insufficient memory to create the key ( pthread_key_create() only).
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO