TSS(3C) | Standard C Library Functions | TSS(3C) |
tss
, tss_create
,
tss_delete
, tss_get
,
tss_set
— thread-specific
storage
#include
<threads.h>
typedef void (*tss_dtor_t)(void *);
int
tss_create
(tss_t *key,
tss_dtor_t dtor);
void
tss_delete
(tss_t key);
void *
tss_get
(tss_t key);
int
tss_set
(tss_t key,
void *val);
The tss family of functions create, get, set, and destroy thread-specific storage.
The
tss_create
()
function creates a new thread-specific data key. The key space is opaque and
global to all threads in the process. Each thread has its own value-space
which can be manipulated with the
tss_get
()
and
tss_set
()
functions. A given key persists until tss_delete
()
is called.
When a key is created, the value NULL
is
associated with all current threads. When a thread is created, the value
NULL
is assigned as the value for the entire
key-space.
A key may optionally be created with a destructor function
dtor. The function dtor will run
when the thread exits (see
thrd_exit(3C)) if the value for
the key is not NULL
. The key space's destructors may
be run in any order. When the destructor is run due to a thread exiting, all
signals will be blocked.
The
tss_delete
()
function deletes the key identified by key from the
global name-space. When a key is deleted, no registered destructor is
called, it is up to the calling program to free any storage that was
associated with key across all threads. Because of
this property, it is legal to call tss_delete
() from
inside a destructor. Any destructors that had been associated with
key will no longer be called when a thread
terminates.
The tss_get
() function may be used to
obtain the value associated with key for the calling
thread. Note that if the calling thread has never set a value, then it will
receive the default value, NULL
.
tss_get
() may be called from a tss destructor.
The tss_set
() function sets the value of
the key key for the calling thread to
value, which may be obtained by subsequent calls to
tss_get. To remove a value for a specific thread, one
may pass NULL
in as value.
Changing the value of a key with tss_set
() does not
cause any destructors to be invoked. This means that
tss_set
() may be used in the context of a
destructor, but special care must be taken to avoid leaking storage or
causing an infinite loop.
Upon successful completion, the
tss_create
() and tss_set
()
functions return
thrd_success.
Otherwise, they return
thrd_error
to indicate that an error occurred.
Upon successful completion, the tss_get
()
function returns the thread-specific value associated with the given
key. If no thread-specific value is associated with
the key or an invalid key was passed in, then NULL
is returned.
pthread_getspecific(3C), pthread_key_create(3C), pthread_key_delete(3C), pthread_setspecific(3C), attributes(7)
November 8, 2020 | OmniOS |