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.
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
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.
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
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_localcaches 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_localover locks for per-thread accumulators (statistics, random engines) and combine results at the end. - Differences from
static:statichas one copy for the whole program;thread_localhas one per thread. A block-scopethread_localis implicitlystaticin 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_localacross a suspension point. - Available since C++11. The C equivalent is
_Thread_local(C11) orthread_local(C23).