上下文变量对象¶

在 3.7 版本加入。

3.7.1 版中的变更

备注

在 Python 3.7.1 中，所有上下文变量 C API 的签名都已更改，以使用 PyObject 指针，而不是 PyContext、PyContextVar 和 PyContextToken，例如。

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

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

有关更多详细信息，请参阅 bpo-34762。

本节详细介绍了 contextvars 模块的公共 C API。

类型检查宏

int PyContext_CheckExact(PyObject *o)¶: 如果 o 的类型为 PyContext_Type，则返回 true。 o 不得为 NULL。此函数总是成功。

int PyContextVar_CheckExact(PyObject *o)¶: 如果 o 的类型为 PyContextVar_Type，则返回 true。 o 不得为 NULL。此函数总是成功。

int PyContextToken_CheckExact(PyObject *o)¶: 如果 o 的类型为 PyContextToken_Type，则返回 true。 o 不得为 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 注册为当前解释器的上下文对象监视器。返回一个 ID，该 ID 可以传递给 PyContext_ClearWatcher()。如果发生错误（例如，没有更多的监视器 ID 可用），则返回 -1 并设置异常。

在 3.14 版本加入。

int PyContext_ClearWatcher(int watcher_id)¶: 清除由 watcher_id 标识的监视器，该 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 将指向

除了 NULL 之外，该函数返回一个新引用。

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)¶: 返回值：新引用。
在当前上下文中将 var 的值设置为 value。返回此更改的新令牌对象，如果发生错误，则返回 NULL。

int PyContextVar_Reset(PyObject *var, PyObject *token)¶: 将 var 上下文变量的状态重置为调用返回 token 的 PyContextVar_Set() 之前它所处的状态。此函数在成功时返回 0，在错误时返回 -1。