The thread Attribute

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 Topics, and see the API Programmer’s Reference in the Microsoft Win32® Software Development Kit.

The C and C++ languages include the extended storage-class attribute, thread. The thread attribute must be used with the __declspec keyword to declare a thread variable. 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
  

• 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 {
  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:

  #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++.