Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

A thread-local variable in C is a variable with thread storage duration, meaning each thread in a multithreaded program receives its own independent, isolated instance of the variable. The memory for the variable is allocated when a thread is created and automatically deallocated when that specific thread terminates. Introduced in the C11 standard, thread-local variables are declared using the _Thread_local storage-class specifier. Including the <threads.h> standard library header provides the thread_local convenience macro, which expands to _Thread_local. 
#include <threads.h>

// Using the C11 keyword directly
_Thread_local int thread_state;

// Using the macro from <threads.h>
thread_local double thread_metric = 0.0;

​
Technical Characteristics

Storage Duration and Scope Applying thread_local alters the storage duration of a variable to thread storage duration. It can be applied to variables at file scope (globals) or block scope (inside functions). According to the C11 standard (6.7.1), if _Thread_local is used on a block-scope declaration, it cannot be used alone; it must be explicitly accompanied by either the static or extern keyword. Linkage The linkage of a thread-local variable depends on its declaration context and accompanying specifiers:
  • External Linkage: File-scope declarations without the static keyword, or block-scope declarations with the extern keyword.
  • Internal Linkage: File-scope declarations combined with the static keyword.
  • No Linkage: Block-scope declarations combined with the static keyword.
#include <threads.h>

// External linkage, thread storage duration
thread_local int global_t_var = 10;

// Internal linkage, thread storage duration
static thread_local int internal_t_var = 20;

void process_data() {
    // No linkage, thread storage duration
    // Must include 'static' (or 'extern') at block scope
    static thread_local int block_t_var = 30; 
}
Initialization Rules In C, thread-local variables must be initialized with a constant expression. Initialization occurs at thread startup (C11 Standard 6.2.4), before the thread executes any code. For the initial (main) thread, initialization occurs at program startup. Unlike C++, C does not perform lazy initialization upon the first evaluation of the variable. If no explicit initializer is provided, the variable is implicitly zero-initialized. Addressability and Pointers Applying the address-of operator (&) to a thread-local variable yields a pointer to the specific instance belonging to the calling thread. While it is syntactically valid to pass this pointer to another thread, doing so requires strict lifetime management; dereferencing the pointer after the owning thread has terminated results in undefined behavior.

​
Pre-C11 Compiler Extensions

For codebases predating C11 or operating on non-compliant compilers, thread-local storage is typically implemented via compiler-specific extensions rather than standard keywords: 
// GCC / Clang / Intel
__thread int gcc_thread_var;

// Microsoft Visual C++ (MSVC)
__declspec(thread) int msvc_thread_var;
Master C with Deep Grasping Methodology!Learn More