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

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

A class for declaring a dynamic thread-local variable (Large/Non-trivial 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.

inline ~ThreadLocal()

Destructor.

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

inline T *get_if()

Returns the value of this ThreadLocal variable for this specific thread, if it has been constructed.

If the calling thread has not called get() or set(const T&) on *this yet, calling this function will return nullptr.

Note

This function is only available for the non-trivial specialization of ThreadLocal.

Returns: nullptr if set(const T&) or get() has not been called by this thread on *this yet; otherwise returns std::addressof(get()).

inline const T *get_if() const

Returns the value of this ThreadLocal variable for this specific thread, if it has been constructed.

If the calling thread has not called get() or set(const T&) on *this yet, calling this function will return nullptr.

Note

This function is only available for the non-trivial specialization of ThreadLocal.

Returns: nullptr if set(const T&) or get() has not been called by this thread on *this yet; otherwise returns std::addressof(get()).

inline T &get()

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-constructed.

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

inline const 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-constructed.

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

inline void set(const T &t)

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

Note

If this is the first time set() has been called for this thread, the stored value is first default- constructed and then t is copy-assigned to the thread-local value.

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

inline void set(T &&t)

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

Note

If this is the first time set() has been called for this thread, the stored value is first default- constructed and then t is move-assigned to the thread-local value.

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

inline void reset(): Clears the specific value of this ThreadLocal variable for this thread.

Note

This function is only available on the non-trivial specialization of ThreadLocal. Postcondition: get_if() returns nullptr.

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=(const T &rhs)

Assignment operator and alias for set().

Returns: *this

inline ThreadLocal &operator=(T &&rhs)

Assignment operator and alias for set().

Returns: *this

inline auto operator->()

Pass-through support for operator->.

Returns: the value of operator->.

inline auto operator->() const

Pass-through support for operator->.

Returns: the value of operator->.

inline auto operator*()

Pass-through support for operator*.

Returns: the value of operator*.

inline auto operator*() const

Pass-through support for operator*.

Returns: the value of operator*.

template<class U> inline auto operator[](const U &u) const

Pass-through support for operator[].

Parameters: u – The value to pass to operator[].
Returns: the value of operator[].

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.