Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Keywords and Statements

The thread_local storage duration

Reference for C++ thread_local: one copy of a variable per thread, lifetime and initialization rules, static locals, caches and common pitfalls.

thread_local gives a variable thread storage duration: every thread gets its own independent copy, created when the thread starts (or on first use) and destroyed when the thread ends. Because no two threads share the object, accessing it needs no locking.

Use it for per-thread caches, scratch buffers, error codes (like errno), random-number engines and "current context" pointers. Do not use it to hide shared state: a thread_local that is passed by pointer to another thread becomes shared again.

C++
thread_local int counter = 0;          // namespace scope: one per thread
void f() { thread_local std::string buf; buf += 'x'; }   // one per thread, kept between 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++ Function-local thread_local and per-thread caches

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 type name = initializer;       // namespace scope or class static member
static thread_local type name;              // internal linkage
extern thread_local type name;              // declaration only
void f() { thread_local type name; }        // block scope: implicitly static
Aspect Rule
Allowed on Namespace-scope variables, block-scope variables and static data members. Not on non-static data members or function parameters. A block-scope thread_local is implicitly static.
Lifetime From thread start (or first use for block-scope ones) to thread exit. The main thread's copies are destroyed when main returns, before objects with static storage duration.
Initialization Dynamic initialization of namespace-scope thread_local runs per thread before first odr-use; constant-initialized ones cost nothing. Block-scope: on first execution of the declaration in that thread.
Destruction In reverse order of construction, when the thread exits.
Combination May appear with static or extern; with constexpr or inline it can be used in headers.

Errors / undefined behavior: using a thread_local object through a pointer after its owning thread has exited is undefined behavior (a dangling pointer).

Usage notes

  • Cost. Access can be slower than for ordinary globals, especially for variables with non-trivial constructors/destructors, because the compiler may need a guard check and registration for destruction. Variables with constant initialization and trivial destruction are as cheap as plain thread-local access.
  • Thread pools. Threads in a pool live a long time, so thread_local caches persist across tasks. That is great for scratch buffers but a source of stale state bugs.
  • Do not pass the address to other threads unless you guarantee the owner outlives them.
  • Prefer thread_local over locks for per-thread accumulators (statistics, random engines) and combine results at the end.
  • Differences from static: static has one copy for the whole program; thread_local has one per thread. A block-scope thread_local is implicitly static in the sense that it persists between calls.
  • Coroutines: a coroutine may resume on a different thread, so do not keep a reference to a thread_local across a suspension point.
  • Available since C++11. The C equivalent is _Thread_local (C11) or thread_local (C23).