Содержание страницы

Поддержка локальной памяти потока¶Thread-local storage support

Интерпретатор Python предоставляет низкоуровневую поддержку локальной памяти потока (TLS), которая служит обёрткой над соответствующей нативной реализацией и обеспечивает работу API локальной памяти потока на уровне Python (threading.local). Низкоуровневые API CPython похожи на те, что предлагают pthreads и Windows: используется ключ потока и функции для связывания значения void* с каждым потоком.

A thread state does not need to be attached when calling these functions; they supply their own locking.

Обратите внимание, что Python.h не содержит объявления TLS-функций; для использования локальной памяти потока необходимо включить pythread.h.

Примечание

Ни одна из этих функций API не занимается управлением памятью для значений void*. Вы должны сами выделять и освобождать память. Если значения void* оказываются PyObject*, эти функции также не выполняют операции с подсчётом ссылок.

API хранения, привязанного к потоку¶Thread-specific storage API

API для хранения, привязанного к потоку (TSS), был введён для замены существующего TLS API внутри интерпретатора CPython. Этот API использует новый тип Py_tss_t вместо int для представления ключей потоков.

Добавлено в версии 3.7.

См. также

«Новый C-API для локальной памяти потока в 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.

Динамическое выделение¶Dynamic allocation

Динамическое выделение Py_tss_t требуется в модулях расширения, собранных с Py_LIMITED_API, где статическое размещение этого типа невозможно из-за того, что его реализация скрыта во время сборки.

Py_tss_t *PyThread_tss_alloc()¶: Часть Stable ABI начиная с версии 3.7.
Возвращает значение, находящееся в том же состоянии, что и значение, инициализированное с помощью Py_tss_NEEDS_INIT, или NULL в случае ошибки динамического выделения.

void PyThread_tss_free(Py_tss_t *key)¶: Часть Stable ABI начиная с версии 3.7.
Освобождает заданный key, выделенный с помощью PyThread_tss_alloc(), предварительно вызвав PyThread_tss_delete(), чтобы сбросить все привязанные к нему локальные данные потока. Эта операция ничего не делает, если аргумент key равен NULL.

Примечание

Освобождённый ключ становится висячим указателем. Следует сбросить ключ обратно в NULL.

Методы¶Methods

Параметр key этих функций не должен быть NULL. Кроме того, поведение PyThread_tss_set() и PyThread_tss_get() не определено, если заданный Py_tss_t не был инициализирован с помощью PyThread_tss_create().

int PyThread_tss_is_created(Py_tss_t *key)¶: Часть Stable ABI начиная с версии 3.7.
Возвращает ненулевое значение, если заданный Py_tss_t был инициализирован с помощью PyThread_tss_create().

int PyThread_tss_create(Py_tss_t *key)¶: Часть Stable ABI начиная с версии 3.7.
Возвращает нулевое значение при успешной инициализации TSS-ключа. Поведение не определено, если значение, на которое указывает аргумент key, не инициализировано с помощью Py_tss_NEEDS_INIT. Эту функцию можно вызывать для одного и того же ключа многократно – вызов для уже инициализированного ключа ничего не делает и сразу возвращает успех.

void PyThread_tss_delete(Py_tss_t *key)¶: Часть Stable ABI начиная с версии 3.7.
Уничтожает TSS-ключ, забывая связанные с ним значения во всех потоках, и переводит состояние инициализации ключа в «не инициализирован». Уничтоженный ключ можно повторно инициализировать с помощью PyThread_tss_create(). Эту функцию можно вызывать для одного и того же ключа многократно – вызов для уже уничтоженного ключа ничего не делает.

int PyThread_tss_set(Py_tss_t *key, void *value)¶: Часть Stable ABI начиная с версии 3.7.
Возвращает нулевое значение при успешной привязке значения void* к TSS-ключу в текущем потоке. Каждый поток имеет собственное отображение ключа на значение void*.

void *PyThread_tss_get(Py_tss_t *key)¶: Часть Stable ABI начиная с версии 3.7.
Возвращает значение void*, связанное с ключом TSS в текущем потоке. Возвращает NULL, если с ключом в текущем потоке не связано никакого значения.

Устаревшие API¶Legacy APIs

Устарело с версии 3.7: Этот API заменён на API для локальных хранилищ потоков (TSS).

Примечание

Эта версия API не поддерживает платформы, где нативный ключ TLS определён так, что его нельзя безопасно привести к int. На таких платформах PyThread_create_key() немедленно возвращает статус ошибки, а остальные функции TLS на таких платформах ничего не делают.

Из-за упомянутой выше проблемы совместимости эту версию API не следует использовать в новом коде.

int PyThread_create_key()¶: Часть Stable ABI.

void PyThread_delete_key(int key)¶: Часть Stable ABI.

int PyThread_set_key_value(int key, void *value)¶: Часть Stable ABI.

void *PyThread_get_key_value(int key)¶: Часть Stable ABI.

void PyThread_delete_key_value(int key)¶: Часть Stable ABI.

void PyThread_ReInitTLS()¶: Часть Stable ABI.