thr_keycreate(3thread)
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(3thread).
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(3synch)).
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(3thread),
Intro(3synch),
mutex(3synch),
thr_exit(3thread),
thr_getspecific(3thread),
thr_keydelete(3thread),
thr_setspecific(3thread)
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);
}
}
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004