Thread Local Storage

Declared in:  be/support/TLS.h
Library: libbe.so
Summary:  more...

The Thread Local Storage (TLS) functions let you create global variables that refer to different data depending on the thread from which the variables are referenced. In essence, TLS variables let you extend the data that's associated with a given thread. This can be particularly important when you're porting code that wasn't designed for a multi-threaded system.

To create a TLS variable, you call tls_allocate():

int32 myName = tls_allocate(); int32 myStatus = tls_allocate();

You only allocate a given TLS variable once (i.e. you don't allocate the same variable in each thread). Typically, you would call tls_allocate() from an app-initialization routine.

To set and retrieve the value of a TLS variable, you call tls_set() and tls_get():

void SetName(const char *name) {    tls_set(myName, (void *)name); } void SetStatus(int32 state) {    tls_set(myStatus, (void *)(int32 *)&state); } void Report() {    if (tls_get(myStatus) != B_OK) {       printf("Error in %sn", tls_get(myName); }

The values that tls_set() and tls_get() set and return are thread-specific; in the examples above, each thread has its own values for myName and myStatus. Note that tls_set() and tls_get() operate in the context of the calling thread only—you can't set or retrieve a TLS value for some other thread.

You never access a TLS variable (i.e. the value returned by tls_allocate()) directly. You may only use it as an argument to the other TLS functions.

Thread Local Storage Functions

tls_allocate()

int32 tls_allocate(void)

Creates and returns a new TLS variable. Each thread in your application will have its own copy of this variable; setting the value of the variable (through tls_set()) in one thread won't affect its value in any other thread. You should only allocate a TLS variable once per team—you don't have to allocate it in each thread.

The memory for the variable's data isn't allocated by tls_allocate(); see tls_set() for more information on TLS memory allocation).

tls_address()

void *tls_address(int32 tlsVariable)

Returns the address of the memory that holds the value that's referred to by tlsVariable. The latter is a TLS variable that must have been created through tls_allocate(). The value returned is valid for the calling thread only.

tls_set() , tls_get()

void tls_set(int32 tlsVariable, void *data) void *tls_get(int32 tlsVariable)

tls_sets() sets tlsVariable to refer to data within the context of the calling thread. data, which must already be allocated, can point to data of any size or type. The data needn't be the same type or size for each thread; for example, a given TLS variable hodgePodge can refer to a string in one thread, an integer in another, an object in another, and so on.

tls_get() returns a pointer to the data referred to by tlsVariable within the context of the calling thread. If tlsVariable hasn't been allocated (tls_allocate()), or if its value hasn't been set (tls_set()), the function returns NULL.