OpenKODE Core extension: KD_KHR_thread_storage


NameKHR_thread_storage
Name stringsKD_KHR_thread_storage
ContributorsMikko Strandborg
ContactsThe OpenKODE Working Group, Khronos
StatusApproved by OpenKODE working group February 2008
VersionVersion 5, 2008-06-20
Number6
Dependencies Requires OpenKODE Core 1.0. This extension is written based on the wording of the OpenKODE Core 1.0 specification.

1. Overview

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.

2. Header file

When this extension is present, its facilities are accessed by including its header file:

#include <KD/KHR_thread_storage.h>

3. New types

3.1. KDThreadStorageKeyKHR

The representation of a thread storage key.

Synopsis

typedef KDuint32 KDThreadStorageKeyKHR;

Description

The type represents the global key that can be used to access thread-local data.

4. New functions

4.1. kdMapThreadStorageKHR

Maps an arbitrary pointer to a global thread storage key.

Synopsis

KDThreadStorageKeyKHR KD_APIENTRY kdMapThreadStorageKHR(const void *  id);

Description

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.

Return value

On success, returns a new globally valid thread storage key. On error returns 0 and sets OpenKODE error code. Currently the only defined error code is KD_ENOMEM if the system runs out of memory or other resources.

4.2. kdSetThreadStorageKHR

Stores thread-local data.

Synopsis

KDint KD_APIENTRY kdSetThreadStorageKHR(KDThreadStorageKeyKHR  key,
 void *  data);

Description

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.

Return value

0 on success. On error returns nonzero and sets OpenKODE error code. Currently the only defined error code is KD_ENOMEM if the system runs out of memory or other resources.

4.3. kdGetThreadStorageKHR

Retrieves previously stored thread-local data.

Synopsis

void * KD_APIENTRY kdGetThreadStorageKHR(KDThreadStorageKeyKHR  key);

Description

Retrieves a data pointer from the current thread's context. If key is not a valid storage key returned from a previous call to kdMapThreadStorageKHR(), undefined behavior results. The initial value of the data pointer for a valid key is KD_NULL.

Return value

The data previously stored by a call to kdSetThreadStorageKHR within the current thread's context, or KD_NULL if kdSetThreadStorageKHR has not been succesfully called with the given key within the current thread's context.

5. Revision history

5.1. Version 5, 2008-06-20

Changed back to being based on OpenKODE Core 1.0 specification.

5.2. Version 4, 2008-03-31

Now based on OpenKODE Core 1.0.1 specification.

5.3. Version 3, 2007-10-19

Rewritten based on feedback from the group.Introduced the concept of TLS key to speed up data retrieval/storage system.

5.4. Version 2, 2007-10-15

Added rationale in the Overview-section.

5.5. Version 1, 2007-10-15

Initial version.