thr_keycreate(3thread) thr_keycreate(3thread)
NAME
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 *value));
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
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
may 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 synch(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 below), the destructor is called
with the bound value.
There is no fixed limit on the number of keys per process.
key Parameter
key points to the thread_key_t in which thr_keycreate will
store the newly created key.
Copyright 1994 Novell, Inc. Page 1
thr_keycreate(3thread) thr_keycreate(3thread)
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 may 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, as described below.
Errors
If any of the following conditions is detected, thr_keycreate
returns the corresponding value:
ENOMEM Insufficient memory exists to create the key.
USAGE
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.
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;
Copyright 1994 Novell, Inc. Page 2
thr_keycreate(3thread) thr_keycreate(3thread)
(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);
}
}
REFERENCES
mutex(3synch), synch(3synch), thr_exit(3thread),
thr_getspecific(3thread), thr_keydelete(3thread),
thr_setspecific(3thread), thread(3thread)
Copyright 1994 Novell, Inc. Page 3