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.
thread_local int calls = 0; // every thread counts its own calls void work() { ++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 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_localvariable 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.
mainthread: itsthread_localobjects 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.