TlsAlloc 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.
Syntax
DWORD TlsAlloc(VOID);Parameters
This function has no parameters.
Return Value
If the function succeeds, it returns a TLS index. If the function fails, it returns 0xFFFFFFFF. Call GetLastError to get extended error information.
The process threads can use the TLS index in subsequent calls to TlsFree, TlsSetValue, or TlsGetValue.
TLS indexes are typically allocated during process or dynamic-link library (DLL) initialization. Once allocated, each process thread 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. For all systems, this minimum is guaranteed to be at least 64.
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 TlsFree as follows:
- 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 DLL global or static variable.
- 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.
- 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.
Note: Since DllMain is only called for RTDLLs at process attach (and not thread attach) it can only be used in an RTDLL to maintain per-process data for the initializing thread. It cannot be used in an RTDLL to maintain thread local storage for any additional threads.
Requirements
| Minimum supported version | Header | Library |
|---|---|---|
|
wRTOS 1.0 SDK |
windows.h |
wRTOS_rtss.lib |
See Also:
