`tls.md`

126 строк · 11.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/c-api/tls.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Поддержка локальной памяти потока89Интерпретатор Python предоставляет низкоуровневую поддержку локальной памяти потока (TLS), которая служит обёрткой над соответствующей нативной реализацией и обеспечивает работу API локальной памяти потока на уровне Python ([`threading.local`](https://python-all.ru/3.16/library/threading.html#threading.local)). Низкоуровневые API CPython похожи на те, что предлагают pthreads и Windows: используется ключ потока и функции для связывания значения void\* с каждым потоком.1011A [thread state](https://python-all.ru/3.16/glossary.html#term-thread-state) does *not* need to be [attached](https://python-all.ru/3.16/glossary.html#term-attached-thread-state) when calling these functions; they supply their own locking.1213Обратите внимание, что `Python.h` не содержит объявления TLS-функций; для использования локальной памяти потока необходимо включить `pythread.h`.1415> **Примечание**16>17> Ни одна из этих функций API не занимается управлением памятью для значений void\*. Вы должны сами выделять и освобождать память. Если значения void\* оказываются [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\*, эти функции также не выполняют операции с подсчётом ссылок.1819## API хранения, привязанного к потоку2021API для хранения, привязанного к потоку (TSS), был введён для замены существующего TLS API внутри интерпретатора CPython. Этот API использует новый тип [`Py_tss_t`](https://python-all.ru/3.16/c-api/tls.html#c.Py_tss_t) вместо int для представления ключей потоков.2223Добавлено в версии 3.7.2425> **См. также**26>27> «Новый C-API для локальной памяти потока в CPython» ([**PEP 539**](https://python-all.ru/3.16/c-api/tls.html))2829#### `type Py_tss_t`3031Эта структура данных представляет состояние ключа потока; её определение может зависеть от конкретной реализации TLS, и она содержит внутреннее поле, отражающее состояние инициализации ключа. Открытых членов этой структуры нет.3233Если [Py\_LIMITED\_API](https://python-all.ru/3.16/c-api/stable.html#stable) не определён, допускается статическое размещение этого типа с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3.16/c-api/tls.html#c.Py_tss_NEEDS_INIT).3435#### `Py_tss_NEEDS_INIT`3637Этот макрос раскрывается в инициализатор для переменных типа [`Py_tss_t`](https://python-all.ru/3.16/c-api/tls.html#c.Py_tss_t). Обратите внимание, что этот макрос не будет определён вместе с [Py\_LIMITED\_API](https://python-all.ru/3.16/c-api/stable.html#stable).3839## Динамическое выделение4041Динамическое выделение [`Py_tss_t`](https://python-all.ru/3.16/c-api/tls.html#c.Py_tss_t) требуется в модулях расширения, собранных с [Py\_LIMITED\_API](https://python-all.ru/3.16/c-api/stable.html#stable), где статическое размещение этого типа невозможно из-за того, что его реализация скрыта во время сборки.4243#### `Py_tss_t *PyThread_tss_alloc()`4445*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*4647Возвращает значение, находящееся в том же состоянии, что и значение, инициализированное с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3.16/c-api/tls.html#c.Py_tss_NEEDS_INIT), или `NULL` в случае ошибки динамического выделения.4849#### `void PyThread_tss_free(Py_tss_t *key)`5051*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*5253Освобождает заданный *key*, выделенный с помощью [`PyThread_tss_alloc()`](https://python-all.ru/3.16/c-api/tls.html#c.PyThread_tss_alloc), предварительно вызвав [`PyThread_tss_delete()`](https://python-all.ru/3.16/c-api/tls.html#c.PyThread_tss_delete), чтобы сбросить все привязанные к нему локальные данные потока. Эта операция ничего не делает, если аргумент *key* равен `NULL`.5455> **Примечание**56>57> Освобождённый ключ становится висячим указателем. Следует сбросить ключ обратно в `NULL`.5859## Методы6061Параметр *key* этих функций не должен быть `NULL`. Кроме того, поведение [`PyThread_tss_set()`](https://python-all.ru/3.16/c-api/tls.html#c.PyThread_tss_set) и [`PyThread_tss_get()`](https://python-all.ru/3.16/c-api/tls.html#c.PyThread_tss_get) не определено, если заданный [`Py_tss_t`](https://python-all.ru/3.16/c-api/tls.html#c.Py_tss_t) не был инициализирован с помощью [`PyThread_tss_create()`](https://python-all.ru/3.16/c-api/tls.html#c.PyThread_tss_create).6263#### `int PyThread_tss_is_created(Py_tss_t *key)`6465*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*6667Возвращает ненулевое значение, если заданный [`Py_tss_t`](https://python-all.ru/3.16/c-api/tls.html#c.Py_tss_t) был инициализирован с помощью [`PyThread_tss_create()`](https://python-all.ru/3.16/c-api/tls.html#c.PyThread_tss_create).6869#### `int PyThread_tss_create(Py_tss_t *key)`7071*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*7273Возвращает нулевое значение при успешной инициализации TSS-ключа. Поведение не определено, если значение, на которое указывает аргумент *key*, не инициализировано с помощью [`Py_tss_NEEDS_INIT`](https://python-all.ru/3.16/c-api/tls.html#c.Py_tss_NEEDS_INIT). Эту функцию можно вызывать для одного и того же ключа многократно – вызов для уже инициализированного ключа ничего не делает и сразу возвращает успех.7475#### `void PyThread_tss_delete(Py_tss_t *key)`7677*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*7879Уничтожает TSS-ключ, забывая связанные с ним значения во всех потоках, и переводит состояние инициализации ключа в «не инициализирован». Уничтоженный ключ можно повторно инициализировать с помощью [`PyThread_tss_create()`](https://python-all.ru/3.16/c-api/tls.html#c.PyThread_tss_create). Эту функцию можно вызывать для одного и того же ключа многократно – вызов для уже уничтоженного ключа ничего не делает.8081#### `int PyThread_tss_set(Py_tss_t *key, void *value)`8283*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*8485Возвращает нулевое значение при успешной привязке значения void\* к TSS-ключу в текущем потоке. Каждый поток имеет собственное отображение ключа на значение void\*.8687#### `void *PyThread_tss_get(Py_tss_t *key)`8889*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.7.*9091Возвращает значение void\*, связанное с ключом TSS в текущем потоке. Возвращает `NULL`, если с ключом в текущем потоке не связано никакого значения.9293## Устаревшие API9495Устарело с версии 3.7: Этот API заменён на [API для локальных хранилищ потоков (TSS)](https://python-all.ru/3.16/c-api/tls.html#thread-specific-storage-api).9697> **Примечание**98>99> Эта версия API не поддерживает платформы, где нативный ключ TLS определён так, что его нельзя безопасно привести к `int`. На таких платформах [`PyThread_create_key()`](https://python-all.ru/3.16/c-api/tls.html#c.PyThread_create_key) немедленно возвращает статус ошибки, а остальные функции TLS на таких платформах ничего не делают.100101Из-за упомянутой выше проблемы совместимости эту версию API не следует использовать в новом коде.102103#### `int PyThread_create_key()`104105*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*106107#### `void PyThread_delete_key(int key)`108109*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*110111#### `int PyThread_set_key_value(int key, void *value)`112113*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*114115#### `void *PyThread_get_key_value(int key)`116117*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*118119#### `void PyThread_delete_key_value(int key)`120121*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*122123#### `void PyThread_ReInitTLS()`124125*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*126