上下文变量对象¶
Added in version 3.7.
在 3.7.1 版本发生变更:
备注
在 Python 3.7.1 中,所有上下文变量 C API 的签名被 更改 为使用 PyObject
指针而不是 PyContext
, PyContextVar
以及 PyContextToken
,例如:
// 在3.7.0:
PyContext *PyContext_New(void);
// 在3.7.1+:
PyObject *PyContext_New(void);
请参阅 bpo-34762 了解详情。
本节深入介绍了 contextvars
模块的公用 C API。
-
type PyContext¶
用于表示
contextvars.Context
对象的 C 结构体。
-
type PyContextVar¶
用于表示
contextvars.ContextVar
对象的 C 结构体。
-
type PyContextToken¶
用于表示
contextvars.Token
对象的 C 结构体。
-
PyTypeObject PyContext_Type¶
表示 context 类型的类型对象。
-
PyTypeObject PyContextVar_Type¶
表示 context variable 类型的类型对象。
-
PyTypeObject PyContextToken_Type¶
表示 context variable token 类型的类型对象。
类型检查宏:
-
int PyContext_CheckExact(PyObject *o)¶
如果 o 的类型为
PyContext_Type
则返回真值。 o 必须不为NULL
。 此函数总是会成功执行。
-
int PyContextVar_CheckExact(PyObject *o)¶
如果 o 的类型为
PyContextVar_Type
则返回真值。 o 必须不为NULL
。 此函数总是会成功执行。
-
int PyContextToken_CheckExact(PyObject *o)¶
如果 o 的类型为
PyContextToken_Type
则返回真值。 o 必须不为NULL
。 此函数总是会成功执行。
上下文对象管理函数:
-
int PyContext_AddWatcher(PyContext_WatchCallback callback)¶
注册 callback 作为当前解释器的上下文对象监视器。 返回一个可被传递给
PyContext_ClearWatcher()
的 ID。 当出错时(例如没有可用的监视器 ID),则返回-1
并设置一个异常。Added in version 3.14.
-
int PyContext_ClearWatcher(int watcher_id)¶
清除之前从
PyContext_AddWatcher()
返回的当前解释器中由 watcher_id 所标识的监视器。 成功时返回0
,或者出错时(例如当给定的 watcher_id 未被注册)返回-1
并设置异常。Added in version 3.14.
-
type PyContextEvent¶
由可能的上下文对象监视器事件组成的枚举:
Py_CONTEXT_SWITCHED
: current context 已切换到不同的上下文。 传递给监视回调函数的对象是当前的contextvars.Context
对象,或 None(如果没有当前上下文)。
Added in version 3.14.
-
typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)¶
上下文对象监视器回调函数。传递给回调函数的对象是特定于事件的;有关详细信息,请参阅
PyContextEvent
。如果回调函数设置了返回一个异常,则它必须返回
-1
;此异常将作为不可引发的异常使用PyErr_FormatUnraisable()
打印出来。 在其他情况下它应当返回0
。在进入回调时可能已经设置了尚未处理的异常。 在此情况下,回调应当返回
0
并仍然设置同样的异常。 这意味着该回调可能不会调用任何其他可设置异常的 API 除非它先保存并清空异常状态,并在返回之前恢复它。Added in version 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 的状态重置为它在返回 token 的
PyContextVar_Set()
被调用之前的状态。 此函数成功时返回0
,出错时返回-1
。