carb::thread::ThreadLocal< T, true >

template<class T> class ThreadLocal<T, true> : private detail::ThreadLocalBase

A class for declaring a dynamic thread-local variable (Trivial/Pointer/POD specialization).

This is necessary since C++11 the thread_local storage class specifier can only be used at namespace scope. There is no way to declare a thread_local variable at class scope unless it is static. ThreadLocal is dynamic.

There are two specializations for ThreadLocal: a trivial version and a non-trivial version. The trivial version is designed for types like plain-old-data that are pointer-sized or less. The non-trivial version supports classes and large types. The heap is used for non-trivial ThreadLocal types, however these are lazy-initialize, so the per-thread memory is only allocated when used for the first time. The type is automatically destructed (and the memory returned to the heap) when a thread exits.

On Windows, this class is implemented using Thread Local Storage APIs. On Linux, this class is implemented using pthread_key_t.

Note

Most systems have a limit to the number of thread-local variables available. Each instance of ThreadLocal will consume some of that storage. Therefore, if a class contains a non-static ThreadLocal member, each instance of that class will consume another slot. Use sparingly.

Public Functions

inline ThreadLocal()

Constructor.

Allocates a thread-local storage slot from the operating system.

~ThreadLocal() = default

Destructor.

Returns the previously allocated thread-local storage slot to the operating system.

inline T get() const

Returns the specific value of this ThreadLocal variable for this thread.

Note

If the calling thread has not yet set() a value for this thread-local storage, the value returned will be default-initialized. For POD types this will be initialized to zeros.

Returns: A value previously set for the calling thread by set(), or a zero-initialized value if set() has not been called by the calling thread.

inline void set(T t)

Sets the specific value of this ThreadLocal variable for this thread.

Parameters: t – The specific value to set for this thread.

inline operator T()

Alias for get().

Returns: The value as if by get().

inline operator T() const

Alias for get().

Returns: The value as if by get().

inline ThreadLocal &operator=(T t)

Assignment operator and alias for set().

Returns: *this

inline T operator->() const

For types where T is a pointer, allows dereferencing the thread-local value.

Returns: The value as if by get().

inline auto operator*() const

For types where T is a pointer, allows dereferencing the thread-local value.

Returns: The value as if by set().

inline bool operator==(const T &rhs) const

Tests the thread-local value for equality with rhs.

Parameters: rhs – The parameter to compare against.
Returns: true if the value stored for the calling thread (as if by get()) matches rhs; false otherwise.

inline bool operator!=(const T &rhs) const

Tests the thread-local value for inequality with rhs.

Parameters: rhs – The compare to compare against.
Returns: true if the value stored for the calling thread (as if by get()) does not match rhs; false otherwise.