SunOS man pages : thr_getspecific (3)
Threads Library Functions thr_keycreate(3THR)
NAME
thr_keycreate, thr_setspecific, thr_getspecific - thread-
specific-data functions
SYNOPSIS
cc -mt [ flag... ] file...[ library... ]
#include <thread.h>
int thr_keycreate(thread_key_t *keyp, void (*destructor,
void *value);
int thr_setspecific(thread_key_t key, void *value);
int thr_getspecific(thread_key_t key, void **valuep);
DESCRIPTION
Create Key
In general, thread key creation allocates a key that locates
data specific to each thread in the process. The key is
global to all threads in the process, which allows each
thread to bind a value to the key once the key has been
created. The key independently maintains specific values for
each binding thread. The thr_keycreate() function allocates
a global key namespace, pointed to by keyp, that is visible
to all threads in the process. Each thread is initially
bound to a private element of this key, which allows access
to its thread-specific data.
Upon key creation, a new key is assigned the value NULL for
all active threads. Additionally, upon thread creation, all
previously created keys in the new thread are assigned the
value NULL.
Optionally, a destructor function, destructor, may be asso-
ciated with each key. Upon thread exit, if a key has a non-
NULL destructor function and the thread has a non-NULL value
associated with that key, the destructor function is called
with the current associated value. If more than one destruc-
tor exists for a thread when it exits, the order of destruc-
tor calls is unspecified.
Set Value
Once a key has been created, each thread may bind a new
value to the key using thr_setspecific(). The values are
unique to the binding thread and are
individually maintained. These values continue for the
life of the calling thread.
Proper synchronization of key storage and access must be
ensured by the caller. The value argument to
thr_setspecific() is generally a pointer to a block of
SunOS 5.8 Last change: 5 Jun 1998 1
Threads Library Functions thr_keycreate(3THR)
dynamically allocated memory reserved by the calling thread
for its own use. See EXAMPLES.
At thread exit, the destructor function, which is associated
at time of creation, is called and it uses the specific
key value as its sole argument.
Get Value
thr_getspecific() stores the current value bound to key for
the calling thread into the location pointed to by valuep.
RETURN VALUES
If successful, thr_keycreate(), thr_setspecific() and
thr_getspecific() return 0. Otherwise, an error number is
returned to indicate the error.
ERRORS
If the following conditions occur, thr_keycreate() returns
the corresponding error number:
EAGAIN
The system lacked the necessary resources to create
another thread-specific data key.
ENOMEM
Insufficient memory exists to create the key.
If the following conditions occur, thr_keycreate() and
thr_setspecific() return the corresponding error number:
ENOMEM
Insufficient memory exists to associate the value with
the key.
The thr_setspecific() function returns the corresponding
error number:
EINVAL
The key value is invalid.
EXAMPLES
Example 1: In this example, the thread-specific data in this
function can be called from more than one thread without
special initialization.
For each argument you pass to the executable of this exam-
ple, a thread is created and privately bound to the
string-value of that argument.
/* cc thisfile.c */
#define _REENTRANT
SunOS 5.8 Last change: 5 Jun 1998 2
Threads Library Functions thr_keycreate(3THR)
#include <thread.h>
void *thread_specific_data(), free();
#define MAX_ARGC 20
thread_t tid[MAX_ARGC];
int num_threads;
main( int argc, char *argv[] ) {
int i;
num_threads = argc - 1;
for( i = 0; i < num_threads; i++)
thr_create(NULL, 0, thread_specific_data, argv[i+1]);
for( i = 0; i < num_threads; i++)
thr_join(tid[i], NULL, NULL);
} /* end main */
void *thread_specific_data(char private_data[])
{
static mutex_tkeylock; /* static ensures only one copy of keylock */
static thread_key_tkey;
static intonce_per_keyname = 0;
void *tsd = NULL;
if (!once_per_keyname) {
mutex_lock(&keylock);
if (!once_per_keyname) {
thr_keycreate(&key, free);
once_per_keyname++;
}
mutex_unlock(&keylock);
}
tsd = thr_getspecific(key);
if (tsd == NULL) {
tsd = (void *)malloc(strlen(private_data) + 1);
strcpy(tsd, private_data);
thr_setspecific(key, tsd);
printf("tsd for %d = %s\n",thr_self(),(char *)thr_getspecific(key));
sleep(2);
printf("tsd for %d remains %s\n",thr_self(),(char *)thr_getspecific(key));
}
} /* end thread_specific_data */
void
free(void *v) {
/* application-specific clean-up function */
}
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.8 Last change: 5 Jun 1998 3
Threads Library Functions thr_keycreate(3THR)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
thr_exit(3THR), attributes(5), standards(5)
WARNINGS
The thr_getspecific() and thr_getspecific() functions may
be called either explicitly, or implicitly from a thread-
specific data destructor function. Calling thr_setspecific()
from a destructor may result in lost storage or infinite
loops.
SunOS 5.8 Last change: 5 Jun 1998 4
|
 |
|
|
