线程本地存储支持¶
The Python interpreter provides low-level support for thread-local storage
(TLS) which wraps the underlying native TLS implementation to support the
Python-level thread-local storage API (threading.local). The
CPython C level APIs are similar to those offered by pthreads and Windows:
use a thread key and functions to associate a void* value per
thread.
A thread state does not need to be attached when calling these functions; they supply their own locking.
请注意 Python.h 并不包括 TLS API 的声明，你需要包括 pythread.h 来使用线程本地存储。
备注
这些 API 函数都不会为 void* 的值处理内存管理问题。你需要自己分配和释放它们。如果 void* 值碰巧为 PyObject*，这些函数也不会对它们执行引用计数操作。
Thread-specific storage API¶
The thread-specific storage (TSS) API was introduced to supersede the use of the existing TLS API within the
CPython interpreter. This API uses a new type Py_tss_t instead of
int to represent thread keys.
Added in version 3.7.
参见
"A New C-API for Thread-Local Storage in CPython" (PEP 539)
-
type Py_tss_t¶
该数据结构表示线程键的状态，其定义可能依赖于下层的 TLS 实现，并且它有一个表示键初始化状态的内部字段。该结构体中不存在公有成员。
当未定义 Py_LIMITED_API 时，允许由
Py_tss_NEEDS_INIT执行此类型的静态分配。
-
Py_tss_NEEDS_INIT¶
这个宏将扩展为
Py_tss_t变量的初始化器。请注意这个宏不会用 Py_LIMITED_API 来定义。
动态分配¶
Py_tss_t 的动态分配，在使用 Py_LIMITED_API 编译的扩展模块中是必须的，在这些模块由于此类型的实现在编译时是不透明的因此它不可能静态分配。
-
Py_tss_t *PyThread_tss_alloc()¶
- 属于 稳定 ABI 自 3.7 版起.
返回一个与使用
Py_tss_NEEDS_INIT初始化的值的状态相同的值，或者当动态分配失败时则返回NULL。
-
void PyThread_tss_free(Py_tss_t *key)¶
- 属于 稳定 ABI 自 3.7 版起.
在首次调用
PyThread_tss_delete()以确保任何相关联的线程局部变量已被撤销赋值之后释放由PyThread_tss_alloc()所分配的给定的 key。如果 key 参数为NULL则这将无任何操作。备注
被释放的 key 将变成一个悬空指针。你应当将 key 重置为
NULL。
方法¶
这些函数的形参 key 不可为 NULL。并且，如果给定的 Py_tss_t 还未被 PyThread_tss_create() 初始化则 PyThread_tss_set() 和 PyThread_tss_get() 的行为将是未定义的。
-
int PyThread_tss_is_created(Py_tss_t *key)¶
- 属于 稳定 ABI 自 3.7 版起.
如果给定的
Py_tss_t已通过PyThread_tss_create()被初始化则返回一个非零值。
-
int PyThread_tss_create(Py_tss_t *key)¶
- 属于 稳定 ABI 自 3.7 版起.
当成功初始化一个 TSS 键时将返回零值。如果 key 参数所指向的值未被
Py_tss_NEEDS_INIT初始化则其行为是未定义的。此函数可在相同的键上重复调用 -- 在已初始化的键上调用它将不执行任何操作并立即成功返回。
-
void PyThread_tss_delete(Py_tss_t *key)¶
- 属于 稳定 ABI 自 3.7 版起.
销毁一个 TSS 键以便在所有线程中遗忘与该键相关联的值，并将该键的初始化状态改为未初始化的。已销毁的键可以通过
PyThread_tss_create()再次被初始化。此函数可以在同一个键上重复调用 -- 但在一个已被销毁的键上调用将是无效的。
旧式 API¶
自 3.7 版本弃用: This API is superseded by the thread-specific storage (TSS) API.
备注
这个 API 版本不支持原生 TLS 键采用无法被安全转换为 int 的定义方式的平台。 在这样的平台上，PyThread_create_key() 将立即返回一个失败状态，并且其他 TLS 函数在这样的平台上也都无效。
由于上面提到的兼容性问题，不应在新代码中使用此版本的 API。