Microsoft KB Archive/94804

{|
 * width="100%"|

INFO: Thread Local Storage Overview

 * }

Q94804

-

The information in this article applies to:


 * Microsoft Win32 Application Programming Interface (API), used with:
 * the operating system: Microsoft Windows NT, versions 3.1, 3.5, 3.51, 4.0
 * Microsoft Windows 95
 * the operating system: Microsoft Windows 2000

-

SUMMARY
Thread local storage (TLS) is a method by which each thread in a given process is given a location(s) in which to store thread-specific data.

Four functions exist for TLS: TlsAlloc, TlsGetValue, TlsSetValue, and TlsFree. These functions manipulate TLS indexes, which refer to storage areas for each thread in a process. A given index is valid only within the process that allocated it.

Note that the Visual C++ compiler supports an alternate syntax:

"_declspec( thread )" which can be used in place of directly calling these APIs. Please see the description of _declspec in the VC++ &quot;Language and Run-time Help&quot; helpfile for more information.

MORE INFORMATION
A call to TlsAlloc returns a global TLS index. This one TLS index is valid for every thread within the process that allocated it, and should therefore be saved in a global or static variable.

Thread local storage works as follows: when TlsAlloc is called, every thread within the process has its own private ULONG_PTR-sized space reserved for it (in its stack space, but this is implementation-specific). However, only one TLS index is returned. This single TLS index may be used by each and every thread in the process to refer to the unique space that TlsAlloc reserved for it.

For this reason, TlsAlloc is often called only once. This is convenient for DLLs, which can distinguish between DLL_PROCESS_ATTACH (where the first process's thread is connecting to the DLL) and DLL_THREAD_ATTACH (subsequent threads of that process are attaching). For example, the first thread calls TlsAlloc and stores the TLS index in a global or static variable, and every other thread that attaches to the DLL refers to the global variable to access their local storage space.

Although one TLS index is usually sufficient, a process may have up to TLS_MINIMUM_AVAILABLE indexes (guaranteed to be greater than or equal to 64).

Once a TLS index has been allocated (and stored), the threads within the process may use it to set and retrieve values in their storage spaces. A thread may store any ULONG_PTR-sized value in its local storage (for example, a ULONG_PTR value, a pointer to some dynamically allocated memory, and so forth). The TlsSetValue and TlsGetValue APIs are used for this purpose.

A process should free TLS indexes with TlsFree when it has finished using them. However, if any threads in the process have stored a pointer to dynamically allocated memory within their local storage spaces, it is important to free the memory or retrieve the pointer to it before freeing the TLS index, or it will be lost.

For more information, please see &quot;Using Thread Local Storage&quot; in the &quot;Processes and Threads&quot; overview in the &quot;Win32 Programmer's Reference&quot;.

Example
Thread A within a process calls TlsAlloc, and stores the index returned in the global variable TlsIndex:

  TlsIndex = TlsAlloc; Thread A then allocates 100 bytes of dynamic memory, and stores it in its local storage:

  TlsSetValue( TlsIndex, malloc(100) ); Thread A creates thread B, which stores a handle to a window in its local storage space referred to by TlsIndex.

  TlsSetValue( TlsIndex, (LPVOID)hSomeWindow ); Note that TlsIndex refers to a different location when thread B uses it, than when thread A uses it. Each thread has its own location referred to by the same value in TlsIndex.

Thread B may terminate safely because it does not need to specifically free the value in its local storage.

Before thread A terminates, however, it must first free the dynamically allocated memory in its local storage

  free( TlsGetValue( TlsIndex ) ); and then free the TLS index:

  if ( !TlsFree( TlsIndex ) ) // TlsFree failed. Handle error. Additional query words:

Keywords : kbKernBase kbOSWinNT310 kbOSWinNT350 kbOSWinNT351 kbOSWinNT400 kbOSWin2000 kbThread kbOSWin95 kbDSupport kbGrpDSKernBase

Issue type : kbinfo

Technology : kbAudDeveloper kbWin32sSearch kbWin32API