Macros | Functions
TLS.h File Reference

Functions to use Thread Local Storage. More...

Macros

#define TLS_MAX_KEYS   64
 The maximum number of thread local storage variables. This number is process wide. More...
 

Functions

void ** tls_address (int32 index)
 Retrieve the pointer that refers to the data of this thread at the provided index. More...
 
int32 tls_allocate (void)
 Allocate a unique index to use for storing variables. More...
 
void * tls_get (int32 index)
 Retrieve the data stored for this thread at the provided index. More...
 
void tls_set (int32 index, void *value)
 Set the data of this thread at the provided index. More...
 

Detailed Description

Functions to use Thread Local Storage.

The Thread Local Storage API provides convenient methods to transform global variables in to thread-context sensitive variables. Some applications rely on global variables as a way of intercommunicating between functions and objects, but one of your demands might be that the contents of that variable differs between threads.

The following example demonstrates how an imaginary thread manager that stores per thread data would function. The constructor of this ThreadManager allocates the TLS variables using tls_allocate(). This only has to be done once, and not in every spawned thread! Then, every spawned thread that interacts with this thread manager, should call the InitThread() function. This one associates the supplied thread data with the TLS index using tls_set(). Each thread can get their associated data with GetCurrentThreadData(), which uses tls_get() to retrieve the associated thread data at the provided index.

int32 gThreadName;
int32 gThreadData;
class ThreadManager
{
public:
// General initialisation
ThreadManager() {
gThreadName = tls_allocate();
gThreadStatus = tls_allocate();
};
// Called from the thread entry function
void InitThread(const char *name, void *data) {
tls_set(gThreadName, (void *)name);
tls_set(gThreadData, data);
};
// Can be called from any of the threads. The returned data will be that
// which the thread explicitly set in the InitThread() function
void *GetCurrentThreadData() {
printf("Thread %s asked for its data.\n",
(const char*)tls_get(gThreadName));
return tls_get(gThreadData);
};
};
Note
  1. It is impossible to get data other than from your thread.
  2. There is a limit to the number of TLS variables you can allocate. This limit is define by TLS_MAX_KEYS, but do realize that you share this limit with all the libraries your application is linked to.
  3. The actual global variables, in the example gThreadName and gThreadData, are only indexes. You cannot use these variables to access data without the TLS API.
Since
BeOS R5

Macro Definition Documentation

◆ TLS_MAX_KEYS

#define TLS_MAX_KEYS   64

The maximum number of thread local storage variables. This number is process wide.

Since
BeOS R5

Function Documentation

◆ tls_address()

void ** tls_address ( int32  index)

Retrieve the pointer that refers to the data of this thread at the provided index.

You can use this pointer to directly manipulate your thread data.

Parameters
indexThe index that you retrieved with tls_allocate().
Returns
The pointer to where your thread's data is, or NULL if the index is invalid.
See also
tls_allocate()
tls_set()
tls_get()
Since
BeOS R5

◆ tls_allocate()

int32 tls_allocate ( void  )

Allocate a unique index to use for storing variables.

You should only have to do this once to allocate the global index, which you can reuse in every thread.

Returns
A unique index to which you can associate per thread data. If we overrun the maximum number of keys, as defined by TLS_MAX_KEYS, the function will return B_NO_MEMORY.
See also
tls_get()
tls_set()
tls_address()
Since
BeOS R5

◆ tls_get()

void * tls_get ( int32  index)

Retrieve the data stored for this thread at the provided index.

Parameters
indexThe index that you retrieved with tls_allocate().
Returns
The data you set using tls_set() for this thread, or NULL if there is no data set, or the index is invalid.
See also
tls_allocate()
tls_set()
Since
BeOS R5

◆ tls_set()

void tls_set ( int32  index,
void *  value 
)

Set the data of this thread at the provided index.

It is up to you to make sure the index is valid. Any invalid indices can lead to unpredictable results.

Parameters
indexThe index that you retrieved with tls_allocate().
valueThe data that should be associated with the index for this thread.
See also
tls_allocate()
tls_get()
Since
BeOS R5