Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Concurrency

C++ thread_local storage duration

Reference for the C++ thread_local specifier: one copy of a variable per thread, initialization and destruction rules, static members and when to use it.

thread_local is a storage-duration specifier (C++11). A variable declared thread_local has one separate instance in every thread. The instance is created when the thread first needs it (or when the thread starts, for variables with constant initialization), and it is destroyed when the thread exits. Threads never see each other's copies, so access needs no locking.

You can combine it with static or extern, and apply it to namespace-scope variables, static data members and block-scope variables. Local thread_local variables behave like static locals, but per thread: they are initialized the first time execution passes their declaration in that thread.

C++
thread_local int calls = 0;        // every thread counts its own calls

void work() { ++calls; }

Try it

C++ Each thread has its own copy

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Initialization and destruction per thread

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
thread_local int x;                              // namespace scope
thread_local std::string name = "worker";        // with initializer
static thread_local int cache;                   // internal linkage
extern thread_local int shared_decl;             // declaration only

struct S {
    static thread_local int per_thread;          // static data member
};

void f() {
    thread_local int local = compute();          // initialized once per thread
}
Part Description
thread_local Gives the variable thread storage duration.
Allowed on Namespace-scope variables, static data members, block-scope variables (implicitly static). Not allowed on non-static members, function parameters or functions.
Initializer Dynamic initializers run lazily in each thread on first use (for non-local variables the compiler arranges a check on access).

Returns: not applicable. Errors / undefined behavior: using a thread_local object after it was destroyed during thread exit (for example from another thread-local's destructor) is undefined. Taking its address and passing it to another thread gives that thread a pointer to your copy, which dies when your thread ends.

Usage notes

  • Good uses: per-thread caches, random number generators (thread_local std::mt19937 rng(seed)), scratch buffers, and "current context" pointers such as error state.
  • Bad uses: hiding shared state. A thread_local variable is global to the thread, which makes code harder to test and to reason about. Pass data explicitly when you can.
  • Thread pools: per-thread data lives as long as the pool thread, not as long as a task. Do not assume a task starts with a fresh value.
  • Cost: access is usually a few instructions, but dynamic initialization adds a guard check, and destructors add bookkeeping at thread exit.
  • Order of destruction: thread-local objects are destroyed in reverse order of construction when the thread ends, before static objects are destroyed.
  • main thread: its thread_local objects are destroyed before static storage objects at normal program exit.
  • Coroutines and fibers that move between threads can observe a different copy after a suspension; avoid holding references across co_await.
  • C++ vs C: C23 and C11 spell it _Thread_local (C23: thread_local); the idea is the same.