Объекты переменных контекста

// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);

В этом разделе описан общедоступный C API модуля contextvars.

type PyContext

Структура C, используемая для представления объекта contextvars.Context.

type PyContextVar

Структура C, используемая для представления объекта contextvars.ContextVar.

type PyContextToken

Структура C, используемая для представления объекта contextvars.Token.

PyTypeObject PyContext_Type

Объект типа, представляющий тип контекста.

PyTypeObject PyContextVar_Type

Объект типа, представляющий тип переменной контекста.

PyTypeObject PyContextToken_Type

Объект типа, представляющий тип токена переменной контекста.

Макросы проверки типов:

int PyContext_CheckExact(PyObject *o)

Возвращает true, если o имеет тип PyContext_Type. o не должен быть NULL. Эта функция всегда завершается успешно.

int PyContextVar_CheckExact(PyObject *o)

Возвращает true, если o имеет тип PyContextVar_Type. o не должен быть NULL. Эта функция всегда завершается успешно.

int PyContextToken_CheckExact(PyObject *o)

Возвращает true, если o имеет тип PyContextToken_Type. o не должен быть NULL. Эта функция всегда завершается успешно.

Функции управления объектами контекста:

PyObject *PyContext_New(void)

Возвращаемое значение: новая ссылка.

Создает новый пустой объект контекста. Возвращает NULL, если произошла ошибка.

PyObject *PyContext_Copy(PyObject *ctx)

Возвращаемое значение: новая ссылка.

Создает поверхностную копию переданного объекта контекста ctx. Возвращает NULL, если произошла ошибка.

PyObject *PyContext_CopyCurrent(void)

Возвращаемое значение: новая ссылка.

Создает поверхностную копию контекста текущего потока. Возвращает NULL, если произошла ошибка.

int PyContext_Enter(PyObject *ctx)

Устанавливает ctx в качестве текущего контекста для текущего потока. В случае успеха возвращает 0, а в случае ошибки — -1.

int PyContext_Exit(PyObject *ctx)

Деактивирует контекст ctx и восстанавливает предыдущий контекст в качестве текущего для текущего потока. В случае успеха возвращает 0, а в случае ошибки — -1.

int PyContext_AddWatcher(PyContext_WatchCallback callback)

Регистрирует callback в качестве наблюдателя за объектами контекста для текущего интерпретатора. Возвращает идентификатор, который можно передать в PyContext_ClearWatcher(). В случае ошибки (например, если больше нет доступных идентификаторов наблюдателей) возвращает -1 и устанавливает исключение.

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

int PyContext_ClearWatcher(int watcher_id)

Удаляет наблюдателя с идентификатором watcher_id, ранее возвращенным функцией PyContext_AddWatcher() для текущего интерпретатора. В случае успеха возвращает 0, а в случае ошибки (например, если указанный watcher_id никогда не регистрировался) возвращает -1 и устанавливает исключение.

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

type PyContextEvent

Перечисление возможных событий наблюдателя за объектами контекста:

• Py_CONTEXT_SWITCHED: текущий контекст переключился на другой контекст. Объект, передаваемый функции обратного вызова наблюдателя, — это ставший текущим объект contextvars.Context или None, если текущего контекста нет.

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

typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)

Функция обратного вызова наблюдателя за объектами контекста. Передаваемый ей объект зависит от события; подробности см. в PyContextEvent.

Если при возврате из функции обратного вызова установлено исключение, она должна вернуть -1; это исключение будет выведено как необрабатываемое с помощью PyErr_FormatUnraisable(). В противном случае функция должна вернуть 0.

При входе в функцию обратного вызова уже может быть установлено ожидающее исключение. В этом случае функция обратного вызова должна вернуть 0, оставив то же исключение установленным. Это означает, что функция обратного вызова не может вызывать другие API, способные установить исключение, пока сначала не сохранит и не очистит состояние исключения и не восстановит его перед возвратом.

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

Функции для переменных контекста:

PyObject *PyContextVar_New(const char *name, PyObject *def)

Возвращаемое значение: новая ссылка.

Создает новый объект ContextVar. Параметр name используется для интроспекции и отладки. Параметр def задает значение по умолчанию для переменной контекста или NULL, если значение по умолчанию отсутствует. Если произошла ошибка, функция возвращает NULL.

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

Получает значение переменной контекста. Возвращает -1, если при поиске произошла ошибка, и 0, если ошибки не было, независимо от того, найдено ли значение.

Если переменная контекста найдена, value будет указателем на нее. Если переменная контекста не найдена, value будет указывать на:

• default_value, если он не равен NULL;
• значение по умолчанию переменной var, если оно не равно NULL;
• NULL

За исключением NULL, функция возвращает новую ссылку.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)

Возвращаемое значение: новая ссылка.

Устанавливает для var значение value в текущем контексте. Возвращает новый объект-токен для этого изменения или NULL, если произошла ошибка.

int PyContextVar_Reset(PyObject *var, PyObject *token)

Восстанавливает состояние переменной контекста var, существовавшее до вызова PyContextVar_Set(), вернувшего токен token. В случае успеха функция возвращает 0, а в случае ошибки — -1.