Thread-specific storage API¶

The thread-specific storage (TSS) API was introduced to supersede the use of the existing TLS API within theCPython interpreter. This API uses a new typePy_tss_t instead ofint to represent thread keys.

typePy_tss_t¶

This data structure represents the state of a thread key, the definition ofwhich may depend on the underlying TLS implementation, and it has aninternal field representing the key’s initialization state. There are nopublic members in this structure.

WhenPy_LIMITED_API is not defined, static allocation ofthis type byPy_tss_NEEDS_INIT is allowed.

Py_tss_NEEDS_INIT¶

This macro expands to the initializer forPy_tss_t variables.Note that this macro won’t be defined withPy_LIMITED_API.

Dynamic allocation¶

Dynamic allocation of thePy_tss_t, required in extension modulesbuilt withPy_LIMITED_API, where static allocation of this typeis not possible due to its implementation being opaque at build time.

Py_tss_t*PyThread_tss_alloc()¶

Part of theStable ABI since version 3.7.

Return a value which is the same state as a value initialized withPy_tss_NEEDS_INIT, orNULL in the case of dynamic allocationfailure.

voidPyThread_tss_free(Py_tss_t*key)¶

Part of theStable ABI since version 3.7.

Free the givenkey allocated byPyThread_tss_alloc(), afterfirst callingPyThread_tss_delete() to ensure any associatedthread locals have been unassigned. This is a no-op if thekeyargument isNULL.

Note

A freed key becomes a dangling pointer. You should reset the key toNULL.

Methods¶

The parameterkey of these functions must not beNULL. Moreover, thebehaviors ofPyThread_tss_set() andPyThread_tss_get() areundefined if the givenPy_tss_t has not been initialized byPyThread_tss_create().

intPyThread_tss_is_created(Py_tss_t*key)¶

Part of theStable ABI since version 3.7.

Return a non-zero value if the givenPy_tss_t has been initializedbyPyThread_tss_create().

intPyThread_tss_create(Py_tss_t*key)¶

Part of theStable ABI since version 3.7.

Return a zero value on successful initialization of a TSS key. The behavioris undefined if the value pointed to by thekey argument is notinitialized byPy_tss_NEEDS_INIT. This function can be calledrepeatedly on the same key – calling it on an already initialized key is ano-op and immediately returns success.

voidPyThread_tss_delete(Py_tss_t*key)¶

Part of theStable ABI since version 3.7.

Destroy a TSS key to forget the values associated with the key across allthreads, and change the key’s initialization state to uninitialized. Adestroyed key is able to be initialized again byPyThread_tss_create(). This function can be called repeatedly onthe same key – calling it on an already destroyed key is a no-op.

intPyThread_tss_set(Py_tss_t*key,void*value)¶

Part of theStable ABI since version 3.7.

Return a zero value to indicate successfully associating avoid*value with a TSS key in the current thread. Each thread has a distinctmapping of the key to avoid* value.

void*PyThread_tss_get(Py_tss_t*key)¶

Part of theStable ABI since version 3.7.

Return thevoid* value associated with a TSS key in the currentthread. This returnsNULL if no value is associated with the key in thecurrent thread.

Legacy APIs¶

Due to the compatibility problem noted above, this version of the API should notbe used in new code.

intPyThread_create_key()¶

Part of theStable ABI.

voidPyThread_delete_key(intkey)¶

Part of theStable ABI.

intPyThread_set_key_value(intkey,void*value)¶

Part of theStable ABI.

void*PyThread_get_key_value(intkey)¶

Part of theStable ABI.

voidPyThread_delete_key_value(intkey)¶

Part of theStable ABI.

voidPyThread_ReInitTLS()¶

Part of theStable ABI.