| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _thread-local-storage: |
| 4 |
|
| 5 |
Thread-local storage support |
| 6 |
============================ |
| 7 |
|
| 8 |
The Python interpreter provides low-level support for thread-local storage |
| 9 |
(TLS) which wraps the underlying native TLS implementation to support the |
| 10 |
Python-level thread-local storage API (:class:`threading.local`). The |
| 11 |
CPython C level APIs are similar to those offered by pthreads and Windows: |
| 12 |
use a thread key and functions to associate a :c:expr:`void*` value per |
| 13 |
thread. |
| 14 |
|
| 15 |
A :term:`thread state` does *not* need to be :term:`attached <attached thread state>` |
| 16 |
when calling these functions; they supply their own locking. |
| 17 |
|
| 18 |
Note that :file:`Python.h` does not include the declaration of the TLS APIs, |
| 19 |
you need to include :file:`pythread.h` to use thread-local storage. |
| 20 |
|
| 21 |
.. note:: |
| 22 |
None of these API functions handle memory management on behalf of the |
| 23 |
:c:expr:`void*` values. You need to allocate and deallocate them yourself. |
| 24 |
If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these |
| 25 |
functions don't do refcount operations on them either. |
| 26 |
|
| 27 |
.. _thread-specific-storage-api: |
| 28 |
|
| 29 |
Thread-specific storage API |
| 30 |
--------------------------- |
| 31 |
|
| 32 |
The thread-specific storage (TSS) API was introduced to supersede the use of the existing TLS API within the |
| 33 |
CPython interpreter. This API uses a new type :c:type:`Py_tss_t` instead of |
| 34 |
:c:expr:`int` to represent thread keys. |
| 35 |
|
| 36 |
.. versionadded:: 3.7 |
| 37 |
|
| 38 |
.. seealso:: "A New C-API for Thread-Local Storage in CPython" (:pep:`539`) |
| 39 |
|
| 40 |
|
| 41 |
.. c:type:: Py_tss_t |
| 42 |
|
| 43 |
This data structure represents the state of a thread key, the definition of |
| 44 |
which may depend on the underlying TLS implementation, and it has an |
| 45 |
internal field representing the key's initialization state. There are no |
| 46 |
public members in this structure. |
| 47 |
|
| 48 |
When :ref:`Py_LIMITED_API <stable>` is not defined, static allocation of |
| 49 |
this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed. |
| 50 |
|
| 51 |
|
| 52 |
.. c:macro:: Py_tss_NEEDS_INIT |
| 53 |
|
| 54 |
This macro expands to the initializer for :c:type:`Py_tss_t` variables. |
| 55 |
Note that this macro won't be defined with :ref:`Py_LIMITED_API <stable>`. |
| 56 |
|
| 57 |
|
| 58 |
Dynamic allocation |
| 59 |
------------------ |
| 60 |
|
| 61 |
Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules |
| 62 |
built with :ref:`Py_LIMITED_API <stable>`, where static allocation of this type |
| 63 |
is not possible due to its implementation being opaque at build time. |
| 64 |
|
| 65 |
|
| 66 |
.. c:function:: Py_tss_t* PyThread_tss_alloc() |
| 67 |
|
| 68 |
Return a value which is the same state as a value initialized with |
| 69 |
:c:macro:`Py_tss_NEEDS_INIT`, or ``NULL`` in the case of dynamic allocation |
| 70 |
failure. |
| 71 |
|
| 72 |
|
| 73 |
.. c:function:: void PyThread_tss_free(Py_tss_t *key) |
| 74 |
|
| 75 |
Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after |
| 76 |
first calling :c:func:`PyThread_tss_delete` to ensure any associated |
| 77 |
thread locals have been unassigned. This is a no-op if the *key* |
| 78 |
argument is ``NULL``. |
| 79 |
|
| 80 |
.. note:: |
| 81 |
A freed key becomes a dangling pointer. You should reset the key to |
| 82 |
``NULL``. |
| 83 |
|
| 84 |
|
| 85 |
Methods |
| 86 |
------- |
| 87 |
|
| 88 |
The parameter *key* of these functions must not be ``NULL``. Moreover, the |
| 89 |
behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are |
| 90 |
undefined if the given :c:type:`Py_tss_t` has not been initialized by |
| 91 |
:c:func:`PyThread_tss_create`. |
| 92 |
|
| 93 |
|
| 94 |
.. c:function:: int PyThread_tss_is_created(Py_tss_t *key) |
| 95 |
|
| 96 |
Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized |
| 97 |
by :c:func:`PyThread_tss_create`. |
| 98 |
|
| 99 |
|
| 100 |
.. c:function:: int PyThread_tss_create(Py_tss_t *key) |
| 101 |
|
| 102 |
Return a zero value on successful initialization of a TSS key. The behavior |
| 103 |
is undefined if the value pointed to by the *key* argument is not |
| 104 |
initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called |
| 105 |
repeatedly on the same key -- calling it on an already initialized key is a |
| 106 |
no-op and immediately returns success. |
| 107 |
|
| 108 |
|
| 109 |
.. c:function:: void PyThread_tss_delete(Py_tss_t *key) |
| 110 |
|
| 111 |
Destroy a TSS key to forget the values associated with the key across all |
| 112 |
threads, and change the key's initialization state to uninitialized. A |
| 113 |
destroyed key is able to be initialized again by |
| 114 |
:c:func:`PyThread_tss_create`. This function can be called repeatedly on |
| 115 |
the same key -- calling it on an already destroyed key is a no-op. |
| 116 |
|
| 117 |
|
| 118 |
.. c:function:: int PyThread_tss_set(Py_tss_t *key, void *value) |
| 119 |
|
| 120 |
Return a zero value to indicate successfully associating a :c:expr:`void*` |
| 121 |
value with a TSS key in the current thread. Each thread has a distinct |
| 122 |
mapping of the key to a :c:expr:`void*` value. |
| 123 |
|
| 124 |
|
| 125 |
.. c:function:: void* PyThread_tss_get(Py_tss_t *key) |
| 126 |
|
| 127 |
Return the :c:expr:`void*` value associated with a TSS key in the current |
| 128 |
thread. This returns ``NULL`` if no value is associated with the key in the |
| 129 |
current thread. |
| 130 |
|
| 131 |
|
| 132 |
.. _thread-local-storage-api: |
| 133 |
|
| 134 |
Legacy APIs |
| 135 |
----------- |
| 136 |
|
| 137 |
.. deprecated:: 3.7 |
| 138 |
This API is superseded by the |
| 139 |
:ref:`thread-specific storage (TSS) API <thread-specific-storage-api>`. |
| 140 |
|
| 141 |
.. note:: |
| 142 |
This version of the API does not support platforms where the native TLS key |
| 143 |
is defined in a way that cannot be safely cast to ``int``. On such platforms, |
| 144 |
:c:func:`PyThread_create_key` will return immediately with a failure status, |
| 145 |
and the other TLS functions will all be no-ops on such platforms. |
| 146 |
|
| 147 |
Due to the compatibility problem noted above, this version of the API should not |
| 148 |
be used in new code. |
| 149 |
|
| 150 |
.. c:function:: int PyThread_create_key() |
| 151 |
.. c:function:: void PyThread_delete_key(int key) |
| 152 |
.. c:function:: int PyThread_set_key_value(int key, void *value) |
| 153 |
.. c:function:: void* PyThread_get_key_value(int key) |
| 154 |
.. c:function:: void PyThread_delete_key_value(int key) |
| 155 |
.. c:function:: void PyThread_ReInitTLS() |