tss_create()

Create a thread-specific storage key

Synopsis:

#include <threads.h>

typedef void (*tss_dtor_t)(void*);

int tss_create( tss_t *key,
                tss_dtor_t dtor );

Arguments:

key: A pointer to a tss_t object where the function can store the new key.
dtor: NULL, or a function to be called when you destroy the storage.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The tss_create() function creates a thread-specific storage key that's available to all threads in the process and binds an optional destructor function dtor to the area. If the function completes successfully, the new storage is returned in key.

Note: Although the same key may be used by different threads, the values bound to the key using tss_set() are maintained on a per-thread basis and persist only for the lifetime of the thread.

When you create a key, the value NULL is bound with the key in all active threads. When you create a thread, the value NULL is bound to all defined keys in the new thread.

You can optionally associate a destructor function with each key value. At thread exit, if the key has a non-NULL destructor pointer, and the thread has a non-NULL value bound to the key, the destructor function is called with the bound value as its only argument. The order of destructor calls is undefined if more than one destructor exists for a thread when it exits.

If, after all destructor functions have been called for a thread, there are still non-NULL bound values, the destructor function is called repeatedly a maximum of TSS_DTOR_ITERATIONS times for each non-NULL bound value.

Returns:

thrd_success: Success.
thrd_error: An error occurred.

Classification:

C11

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes

Caveats:

Before each destructor is called, the thread's value for the corresponding key is set to NULL. Calling:

tss_set( key, NULL );

in a key destructor isn't required; this lets you use the same destructor for several keys.