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; thread cannot be used on function declarations or definitions.

• 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.

• 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.

• You cannot use the thread attribute as a type modifier.

• Only POD classes may be instantiated using __declspec(thread). The thread attribute is ignored if no object is declared as part of the class declaration. For example:

  // declspec_thread.cpp
  // compile with: /LD
  __declspec(thread) class X
  {
  public:
     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:

  // declspec_thread_2.cpp
  // compile with: /LD
  __declspec( thread ) class B {
  public:
     int data;
  } BObject;   // BObject declared thread local.
  
  class B2 {
  public:
     int data;
  };
  __declspec( thread ) B2 BObject2;   // BObject2 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:

  // declspec_thread_3.cpp
  // compile with: /LD
  #define Thread __declspec( thread )
  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

Concepts

Reference