GmTLS< T, Align > Class Template Reference

A class that works together with GmThreadManager to provide thread local storage. More...

#include <gmThreadLocalStorage.h>

Collaboration diagram for GmTLS< T, Align >:

Public Types
typedef GmTLS_DataT< T, Align >	DataT
typedef GmTLS_Alloc< DataT, Align >	Alloc

Public Member Functions
	GmTLS ()
	Creates a new thread local storage, with default constructed values.
	GmTLS (const T &defVal)
	Creates a new thread local storage with values initialized to the given default value.
	~GmTLS ()
	Destructor.
void	init (const T &val)
	Initializes the value for ALL threads with the given value.
int	size () const
	Returns the number of values stored in the TLS object. Equal to the max number of threads + 1 (for the main thread)
T &	localData (int tid)
	Returns the given thread local data as a modifiable reference.
const T &	localData (int tid) const
	Returns the given thread local data as a const reference.
T &	localData ()
	Returns the current thread local data as a modifiable reference.
const T &	localData () const
	Returns the current thread local data as a const reference.
void	setLocalData (int tid, const T &data)
	Updates the given thread local data.
void	setLocalData (const T &data)
	Updates the current thread local data.

Private Attributes
DataT *	_data

Detailed Description

template<class T, bool Align = false>
class GmTLS< T, Align >

A class that works together with GmThreadManager to provide thread local storage.

The decalaration of a GmTLS<int> variable creates an array with as many int values as the maximum number of threads configured in the thread manager + 1 extra value for the main thread.

This class is an alternative to declaring a "system" thread local storage by using the macro GmThreadLocal. The main advantage is that the TLS does not need to be a global/static variable and can be heap allocated or an object member. The main disadvantage is that it must be declared AFTER the thread manager creation.

IMPORTANT: It also MUST be deleted BEFORE the thread manager is destroyed.

COROLLARY: As a consequence, one should never create a TLS object as a global variable since its life time will surelly begin before the thread manager is created and end after its destruction.

Each thread local copy can be accessed and set throught the localData() and setLocalData() functions. Those come in two falvours: one that gets as first parameter the current thread id (0 for the main thread and a value between 1 and GmThreadManager::maxWorkerThreads() for task threads) and another that gets the id by calling GmThreadManager::currentId(). The first one can be used to query values from other threads. When doing that, please make sure that you are not creating race conditions.

The second template parameter, Align, is a boolean value that controls if the class will cache align the data. When Align is true, each T value will be padded so that its size becomes a multiple of the cache line (64 bytes for x86).

This can be greatly more efficient when various threads are writting simultaneously to the TLS. Use it to avoid the problem known as "False sharing". Keep in mind that alignment is NOT needed if the thread is not writting to the TLS, just reading from it.

Besides padding when Align is true, variables will also be cache border aligned, making sure that no data is splited between two cache lines if its size is less than the cache line size (which could also lead to false sharing if parts of two entries where on the same cache line, as could happend with any size greater than 16 bytes - the natural malloc alignment)

---

The documentation for this class was generated from the following file:

• inc/threads/gmThreadLocalStorage.h