> **Источник:** https://python-all.ru/3/c-api/tls.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Поддержка локальной памяти потока Интерпретатор Python предоставляет низкоуровневую поддержку локальной памяти потока (TLS), которая служит обёрткой над соответствующей нативной реализацией и обеспечивает работу API локальной памяти потока на уровне Python ([`threading.local`](https://python-all.ru/3/library/threading.html#threading.local)). Низкоуровневые API CPython похожи на те, что предлагают pthreads и Windows: используется ключ потока и функции для связывания значения void\* с каждым потоком. A [thread state](https://python-all.ru/3/glossary.html#term-thread-state) does *not* need to be [attached](https://python-all.ru/3/glossary.html#term-attached-thread-state) when calling these functions; they supply their own locking. Обратите внимание, что `Python.h` не содержит объявления TLS-функций; для использования локальной памяти потока необходимо включить `pythread.h`. > **Примечание** > > Ни одна из этих функций API не занимается управлением памятью для значений void\*. Вы должны сами выделять и освобождать память. Если значения void\* оказываются [PyObject](https://python-all.ru/3/c-api/structures.html#c.PyObject)\*, эти функции также не выполняют операции с подсчётом ссылок. ## API хранения, привязанного к потоку API для хранения, привязанного к потоку (TSS), был введён для замены существующего TLS API внутри интерпретатора CPython. Этот API использует новый тип [`Py_tss_t`](https://python-all.ru/3/c-api/tls.html#c.Py_tss_t) вместо int для представления ключей потоков. Добавлено в версии 3.7. > **См. также** > > «Новый C-API для локальной памяти потока в CPython» ([**PEP 539**](https://python-all.ru/3/c-api/tls.html)) #### `type Py_tss_t` Эта структура данных представляет состояние ключа потока; её определение может зависеть от конкретной реализации TLS, и она содержит внутреннее поле, отражающее состояние инициализации ключа. Открытых членов этой структуры нет. Если [Py\_LIMITED\_API](https://python-all.ru/3/c-api/stable.html#stable) не определён, допускается статическое размещение этого типа с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3/c-api/tls.html#c.Py_tss_NEEDS_INIT). #### `Py_tss_NEEDS_INIT` Этот макрос раскрывается в инициализатор для переменных типа [`Py_tss_t`](https://python-all.ru/3/c-api/tls.html#c.Py_tss_t). Обратите внимание, что этот макрос не будет определён вместе с [Py\_LIMITED\_API](https://python-all.ru/3/c-api/stable.html#stable). ## Динамическое выделение Динамическое выделение [`Py_tss_t`](https://python-all.ru/3/c-api/tls.html#c.Py_tss_t) требуется в модулях расширения, собранных с [Py\_LIMITED\_API](https://python-all.ru/3/c-api/stable.html#stable), где статическое размещение этого типа невозможно из-за того, что его реализация скрыта во время сборки. #### `Py_tss_t *PyThread_tss_alloc()` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.* Возвращает значение, находящееся в том же состоянии, что и значение, инициализированное с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3/c-api/tls.html#c.Py_tss_NEEDS_INIT), или `NULL` в случае ошибки динамического выделения. #### `void PyThread_tss_free(Py_tss_t *key)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.* Освобождает заданный *key*, выделенный с помощью [`PyThread_tss_alloc()`](https://python-all.ru/3/c-api/tls.html#c.PyThread_tss_alloc), предварительно вызвав [`PyThread_tss_delete()`](https://python-all.ru/3/c-api/tls.html#c.PyThread_tss_delete), чтобы сбросить все привязанные к нему локальные данные потока. Эта операция ничего не делает, если аргумент *key* равен `NULL`. > **Примечание** > > Освобождённый ключ становится висячим указателем. Следует сбросить ключ обратно в `NULL`. ## Методы Параметр *key* этих функций не должен быть `NULL`. Кроме того, поведение [`PyThread_tss_set()`](https://python-all.ru/3/c-api/tls.html#c.PyThread_tss_set) и [`PyThread_tss_get()`](https://python-all.ru/3/c-api/tls.html#c.PyThread_tss_get) не определено, если заданный [`Py_tss_t`](https://python-all.ru/3/c-api/tls.html#c.Py_tss_t) не был инициализирован с помощью [`PyThread_tss_create()`](https://python-all.ru/3/c-api/tls.html#c.PyThread_tss_create). #### `int PyThread_tss_is_created(Py_tss_t *key)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.* Возвращает ненулевое значение, если заданный [`Py_tss_t`](https://python-all.ru/3/c-api/tls.html#c.Py_tss_t) был инициализирован с помощью [`PyThread_tss_create()`](https://python-all.ru/3/c-api/tls.html#c.PyThread_tss_create). #### `int PyThread_tss_create(Py_tss_t *key)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.* Возвращает нулевое значение при успешной инициализации TSS-ключа. Поведение не определено, если значение, на которое указывает аргумент *key*, не инициализировано с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3/c-api/tls.html#c.Py_tss_NEEDS_INIT). Эту функцию можно вызывать для одного и того же ключа многократно – вызов для уже инициализированного ключа ничего не делает и сразу возвращает успех. #### `void PyThread_tss_delete(Py_tss_t *key)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.* Уничтожает TSS-ключ, забывая связанные с ним значения во всех потоках, и переводит состояние инициализации ключа в «не инициализирован». Уничтоженный ключ можно повторно инициализировать с помощью [`PyThread_tss_create()`](https://python-all.ru/3/c-api/tls.html#c.PyThread_tss_create). Эту функцию можно вызывать для одного и того же ключа многократно – вызов для уже уничтоженного ключа ничего не делает. #### `int PyThread_tss_set(Py_tss_t *key, void *value)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.* Возвращает нулевое значение при успешной привязке значения void\* к TSS-ключу в текущем потоке. Каждый поток имеет собственное отображение ключа на значение void\*. #### `void *PyThread_tss_get(Py_tss_t *key)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.7.* Возвращает значение void\*, связанное с ключом TSS в текущем потоке. Возвращает `NULL`, если с ключом в текущем потоке не связано никакого значения. ## Устаревшие API Устарело с версии 3.7: Этот API заменён на [API для локальных хранилищ потоков (TSS)](https://python-all.ru/3/c-api/tls.html#thread-specific-storage-api). > **Примечание** > > Эта версия API не поддерживает платформы, где нативный ключ TLS определён так, что его нельзя безопасно привести к `int`. На таких платформах [`PyThread_create_key()`](https://python-all.ru/3/c-api/tls.html#c.PyThread_create_key) немедленно возвращает статус ошибки, а остальные функции TLS на таких платформах ничего не делают. Из-за упомянутой выше проблемы совместимости эту версию API не следует использовать в новом коде. #### `int PyThread_create_key()` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).* #### `void PyThread_delete_key(int key)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).* #### `int PyThread_set_key_value(int key, void *value)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).* #### `void *PyThread_get_key_value(int key)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).* #### `void PyThread_delete_key_value(int key)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).* #### `void PyThread_ReInitTLS()` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).*