| DWORD TlsAlloc(VOID) |
The TlsAlloc function allocates a TLS (thread local storage) index. This index can be subsequently used to store and retrieve values that are local to a thread.
This function has no parameters.
If the return value is not equal to 0xFFFFFFFF, the function was successful. The return value is a TLS index that may be used in a subsequent call to TlsFree, TlsSetValue, or TlsGetValue. The storage associated with the index is initialized to NULL.
If the return value is equal to 0xFFFFFFFF, the function failed. More detailed error information can be obtained by calling the GetLastError function.
Windows32 guarantees that a minimum number of TLS indexes are available in each process. The constant TLS_MINIMUM_AVAILABLE defines the minimum number of available indexes. This minimum is at least 64 for all Windows32 systems.
TLS indexes are typically allocated during application or DLL initialization. Once allocated, an application or DLL may use a TLS index to access a per-thread TLS storage slot.
TLS indexes are not valid across process boundaries. A DLL can not assume that an index assigned in one process is valid in another process.
A DLL might use TlsAlloc, TlsSetValue, TlsGetValue, and TlsFree as follows:
– Upon DLL initialization, a TLS index will be allocated using TlsAlloc. The DLL will then allocate some dynamic storage and store its address in the TLS slot using TlsSetValue. This completes the per thread initialization for the initial thread of the process. The TLS index is stored in instance data for the DLL.
– Each time a new thread attaches to the DLL, the DLL will allocate some dynamic storage and store its address in the TLS slot using TlsSetValue. This completes the per thread initialization for the new thread.
– Each time an initialized thread makes a DLL call requiring the TLS, the DLL will call TlsGetValue to get the TLS data for the thread.
TlsFree, TlsGetValue, TlsSetValue