TlsAlloc
The TlsAlloc
function allocates a thread local storage (TLS) index. Any thread of the
process can subsequently use this index to store and retrieve values that are
local to the thread.
DWORD TlsAlloc(VOID)
Parameters
This function
has no parameters.
Return Values
If the
function succeeds, the return value is a TLS index.
If the
function fails, the return value is 0xFFFFFFFF. To get extended error
information, call GetLastError.
Remarks
The threads
of the process can use the TLS index in subsequent calls to the TlsFree, TlsSetValue, or TlsGetValue functions.
TLS indexes
are typically allocated during process or dynamic-link library (DLL)
initialization. Once allocated, each thread of the process can use a TLS index
to access its own TLS storage slot. To store a value in its slot, a thread
specifies the index in a call to TlsSetValue. The thread specifies the
same index in a subsequent call to TlsGetValue, to retrieve the stored
value.
The constant
TLS_MINIMUM_AVAILABLE defines the minimum number of TLS indexes available in
each process. This minimum is guaranteed to be at least 64 for all systems.
TLS indexes
are not valid across process boundaries. A DLL cannot assume that an index
assigned in one process is valid in another process.
A DLL might
use TlsAlloc, TlsSetValue, TlsGetValue, and TlsFree3HLLFBU as follows:
1. When a DLL attaches to a process, the DLL uses
TlsAlloc to allocate a TLS index. The DLL then allocates some dynamic
storage and uses the TLS index in a call to TlsSetValue to store the
address in the TLS slot. This concludes the per-thread initialization for the
initial thread of the process. The TLS index is stored in a global or static
variable of the DLL.
2. Each time the DLL attaches to a new thread of
the process, the DLL allocates some dynamic storage for the new thread and uses
the TLS index in a call to TlsSetValue to store the address in the TLS slot.
This concludes the per-thread initialization for the new thread.
3. Each time an initialized thread makes a DLL
call requiring the data in its dynamic storage, the DLL uses the TLS index in a
call to TlsGetValue to retrieve the address of the dynamic storage for
that thread.
For
additional information on thread local storage, see Thread Local Storage.
See Also
TlsFree, TlsGetValue, TlsSetValueD9LJU_