Tribblix: manual page: tss.3c

TSS(3C) Standard C Library Functions TSS(3C)

NAME

tss, tss_create, tss_delete, tss_get, tss_set - thread-specific storage

SYNOPSIS

#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);

DESCRIPTION

The tss family of functions create, get, set, and destroy thread-
specific storage.

Creating and Destroying 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.

Obtaining Values

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.

Setting Values

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.

RETURN VALUES

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.

INTERFACE STABILITY

Standard

MT-LEVEL
MT-Safe