Standard C Library Functions thrkeycreate(3C)
NAME
thrkeycreate, thrkeycreateonce, thrsetspecific,
thrgetspecific - thread-specific data functions
SYNOPSIS
cc -mt [ flag... ] file... [ library... ]
#include
int thrkeycreate(threadkeyt *keyp,
void (*destructor)(void *));
int thrkeycreateonce(threadkeyt *keyp,
void (*destructor)(void *));
int thrsetspecific(threadkeyt key, void *value);
int thrgetspecific(threadkeyt 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 thrkeycreate() 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 NUL for
all active threads. Additionally, upon thread creation, all
previously created keys in the new thread are assigned the
value NUL.
Optionally, a destructor function destructor can be associ-
ated 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.
SunOS 5.11 Last change: 2 Nov 2007 1
Standard C Library Functions thrkeycreate(3C)
An exiting thread runs with all signals blocked. All thread
termination functions, including thread-specific data des-
tructor functions, are called with all signals blocked.
The thrkeycreateonce() function is identical to the
thrkeycreate() function except that the key pointed to by
keyp must be statically initialized with the value
THRONCEKEY before calling thrkeycreateonce() and the key
will be created exactly once. This is equivalent to using
pthreadonce() to call a onetime initialization function
that calls thrkeycreate() to create the data key.
Set Value
Once a key has been created, each thread can bind a new
value to the key using thrsetspecific(). The values are
unique to the binding thread and are individually main-
tained. 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
thrsetspecific() is generally a pointer to a block of
dynamically allocated memory reserved by the calling thread
for its own use. See EXAMPLES below.
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
thrgetspecific() stores the current value bound to key for
the calling thread into the location pointed to by valuep.
RETURN VALUES
If successful, thrkeycreate(), thrkeycreateonce(),
thrsetspecific() and thrgetspecific() return 0. Otherwise,
an error number is returned to indicate the error.
ERORS
If the following conditions occur, thrkeycreate() and
thrkeycreateonce() return 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.
SunOS 5.11 Last change: 2 Nov 2007 2
Standard C Library Functions thrkeycreate(3C)
If the following conditions occur, thrsetspecific() returns
the corresponding error number:
ENOMEM Insufficient memory exists to associate the value
with the key.
The thrsetspecific() function returns the corresponding
error number:
EINVAL The key value is invalid.
EXAMPLES
Example 1 Call the thread-specific data from more than one
thread without special initialization.
In this example, the thread-specific data in this function
can be called from more than one thread without special ini-
tialization. For each argument passed to the executable, a
thread is created and privately bound to the string-value of
that argument.
/* cc -mt thisfile.c */
#include
#include
#include
#include
void *threadspecificdata(void *);
void cleanup(void*);
#define MAXARGC 20
threadt tid[MAXARGC];
int numthreads;
int
main(int argc, char *argv[]) {
int i;
numthreads = argc - 1;
for (i = 0; i < numthreads; i])
thrcreate(NUL, 0, threadspecificdata, argv[i]1], 0, &tid[i]);
for (i = 0; i < numthreads; i])
thrjoin(tid[i], NUL, NUL);
return (0);
} /* end main */
void *
threadspecificdata(void *arg) {
SunOS 5.11 Last change: 2 Nov 2007 3
Standard C Library Functions thrkeycreate(3C)
static threadkeyt key = THRONCEKEY;
char *privatedata = arg;
void *tsd = NUL;
void *data;
thrkeycreateonce(&key, cleanup);
thrgetspecific(key, &tsd);
if (tsd == NUL) {
data = malloc(strlen(privatedata) ] 1);
strcpy(data, privatedata);
thrsetspecific(key, data);
thrgetspecific(key, &tsd);
}
printf("tsd for %d = %s\n", thrself(), (char *)tsd);
thrgetspecific(key, &tsd);
printf("tsd for %d remains %s\n", thrself(), (char *)tsd);
return (NUL);
} /* end threadspecificdata */
void
cleanup(void *v) {
/* application-specific clean-up function */
free(v);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level MT-Safe
SEE ALSO
pthreadonce(3C), threxit(3C), attributes(5), standards(5)
WARNINGS
The thrgetspecific() and thrsetspecific() functions can
be called either explicitly or implicitly from a thread-
specific data destructor function. Calling thrsetspecific()
from a destructor can result in lost storage or infinite
loops.
SunOS 5.11 Last change: 2 Nov 2007 4
|
