This documentation is archived and is not being maintained.


Microsoft Specific

The thread extended storage-class modifier is used to declare a thread local variable.

__declspec( thread ) declarator

Thread Local Storage (TLS) is the mechanism by which each thread in a multithreaded process allocates storage for thread-specific data. In standard multithreaded programs, data is shared among all threads of a given process, whereas thread local storage is the mechanism for allocating per-thread data. For a complete discussion of threads, see Multithreading.

Declarations of thread local variables must use extended attribute syntax and the __declspec keyword with the thread keyword. For example, the following code declares an integer thread local variable and initializes it with a value:

__declspec( thread ) int tls_i = 1;

You must observe these guidelines when declaring thread local objects and variables:

  • You can apply the thread attribute only to data declarations and definitions, and classes that do not have member functions. It cannot be used on function declarations or definitions. For example, the following code generates a compiler error:
    #define Thread   __declspec( thread )
    Thread void func();          // Error
  • The use of the thread attribute may interfere with delay loading of DLL imports.
  • You can specify the thread attribute only on data items with static storage duration. This includes global data objects (both static and extern), local static objects, and static data members of classes. You cannot declare automatic data objects with the thread attribute. For example, the following code generates compiler errors:
    #define Thread   __declspec( thread )
    void func1()
        Thread int tls_i;            // Error
    int func2( Thread int tls_i )    // Error
        return tls_i;
  • You must use the thread attribute for the declaration and the definition of a thread local object, whether the declaration and definition occur in the same file or separate files. For example, the following code generates an error:
    #define Thread   __declspec( thread )
    extern int tls_i;      // This generates an error, because the
    int Thread tls_i;      // declaration and the definition differ.
  • You cannot use the thread attribute as a type modifier. For example, the following code generates a compiler error:
    char __declspec( thread ) *ch;       // Error
  • Classes can be instantiated using thread only if they contain no member functions. The thread attribute is ignored if no object is declared as part of the class declaration. For example:
    __declspec(thread) class X {
       int I; } x;   // x is a thread object
    X y;            // y is not a thread object

    Because the declaration of objects that use the thread attribute is permitted, these two examples are semantically equivalent:

    #define Thread   __declspec( thread )
    Thread class B
       // Code
    } BObject;            // Okay--BObject declared thread local.
    class B
       // Code
    Thread B BObject;     // Okay--BObject declared thread local.
  • Standard C permits initialization of an object or variable with an expression involving a reference to itself, but only for objects of nonstatic extent. Although C++ normally permits such dynamic initialization of an object with an expression involving a reference to itself, this type of initialization is not permitted with thread local objects. For example:
    #define Thread   __declspec( thread )
    Thread int tls_i = tls_i;            // C and C++ error 
    int j = j;                           // Okay in C++; C error
    Thread int tls_i = sizeof( tls_i )   // Okay in C and C++

    Note that a sizeof expression that includes the object being initialized does not constitute a reference to itself and is allowed in C and C++.

END Microsoft Specific

See Also

__declspec | C++ Keywords | Thread Local Storage (TLS)