A Per-Thread Singleton Class

TLS

TLS is a Win32 mechanism that allows multiple threads of a process to store and retrieve data that is unique for each thread. Any one thread allocates an index, and then this index is available for use by all the threads in the process. Each thread in the process has its own TLS slot for this index where a 32-bit pointer to data can be stored and retrieved from. TLS is used as follows:

1. Use the Win32 API TlsAlloc to allocate a TLS index.
2. In a thread that needs to use TLS storage, allocate dynamic storage and then use the Win32 API TlsSetValue to associate the index with a pointer to the dynamic storage.
3. In the same thread, when any piece of code wants to retrieve the data structure stored in the specified TLS index, use the Win32 API TlsGetValue, which retrieves the pointer stored using TlsSetValue.
4. Use the Win32 API TlsFree to free the index when all the threads are done using the index. In addition, each thread must free the dynamic storage it allocated to associate with the TLS index.

The APIs TlsSetValue and TlsGetValue are designed for extremely fast storage and retrieval. As a result, these APIs do minimal parameter checking. For example, as long as the index specified in these APIs is less than the value TLS_MINIMUM_AVAILABLE, these APIs succeed, even though the index may not have been allocated. It is up to the programmer to ensure that the index is valid.