Debian Codegraph @

Doc/c-api/tls.rst

raw
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()