Поддержка потоко-локального хранилища

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

состояние потока не требуется присоединять при вызове этих функций; они обеспечивают собственную блокировку.

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

Примечание

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

API потокоспецифичного хранилища

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

Добавлено в версии 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.

Динамическое выделение памяти

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

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

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

Примечание

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

Методы

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

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

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

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

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

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

Устаревшие API

Устарело с версии 3.7: Этот API заменён API потокоспецифичного хранилища (TSS).

Примечание

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

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

int PyThread_create_key(): Часть стабильного ABI.

void PyThread_delete_key(int key): Часть стабильного ABI.

int PyThread_set_key_value(int key, void *value): Часть стабильного ABI.

void *PyThread_get_key_value(int key): Часть стабильного ABI.

void PyThread_delete_key_value(int key): Часть стабильного ABI.

void PyThread_ReInitTLS(): Часть стабильного ABI.