Name | KHR_thread_storage |
Name strings | KD_KHR_thread_storage |
Contributors | Mikko Strandborg |
Contacts | The OpenKODE Working Group, Khronos |
Status | Approved by OpenKODE working group February 2008 |
Version | Version 5, 2008-06-20 |
Number | 6 |
Dependencies | Requires OpenKODE Core 1.0. This extension is written based on the wording of the OpenKODE Core 1.0 specification. |
This OpenKODE Core extension provides thread-local storage based on unique identifier. The OpenKODE Core 1.0 specification does not provide facilities to declare a variable to be thread-local. Some compilers have a declaration for that (on Windows: __declspec(thread)) but not all compilers have such a feature. kdGet/SetTLS(), on other hand, should be reserved to be used by the application. This extension provides a way for a middleware or any other library to store thread-local data without interfering with other parts of the application potentially using kdGet/SetTLS().
The thread storage data slots are identified by user-defined arbitrary pointers. For example, the application may choose to use the address of the function calling kdMapThreadStorageKHR(), or an address of either globally or statically defined const KDchar string.
In order to improve performance, the system uses two-phase key retrieval. In the first phase, the application maps an arbitrary pointer to a KDThreadStorageKeyKHR type by calling kdMapThreadStorageKHR(). The complexity of this call is O(n) where n is the number of unique keys mapped during the lifetime of the application. The mapping is guaranteed to be globally invariant for the duration of the application's lifetime. In the second phase, the application can store and retrieve the thread-local data by calling kdSetThreadStorageKHR() and kdGetThreadStorageKHR(). The complexity of these calls is O(1).
If the OpenKODE Core implementation supports writable static data, the key can be stored to a global variable to improve the performance of data store/retrieval operations. On platforms where writable static data is not available, the application would have to call kdMapThreadStorageKHR each time it wants to access the stored data. On single-threaded platforms not supporing writable static data this extension can be used to simulate writable global data.
When this extension is present, its facilities are accessed by including its header file:
#include <KD/KHR_thread_storage.h>
Maps an arbitrary pointer to a global thread storage key.
This function maps an arbitrary pointer to a globally valid thread storage key. Multiple calls to kdMapThreadStorageKHR with identical id's are guaranteed to return identical keys during the application's lifetime.
Stores thread-local data.
Stores a data pointer within the current thread's context. If key is not a valid storage key returned from a previous call to kdMapThreadStorageKHR(), undefined behavior results.
Rewritten based on feedback from the group.Introduced the concept of TLS key to speed up data retrieval/storage system.