上下文变量对象

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。 此函数总是会成功执行。

上下文对象管理函数:

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)

Register callback as a context object watcher for the current interpreter. Return an ID which may be passed to PyContext_ClearWatcher(). In case of error (e.g. no more watcher IDs available), return -1 and set an exception.

Added in version 3.14.

int PyContext_ClearWatcher(int watcher_id)

Clear watcher identified by watcher_id previously returned from PyContext_AddWatcher() for the current interpreter. Return 0 on success, or -1 and set an exception on error (e.g. if the given watcher_id was never registered.)

Added in version 3.14.

type PyContextEvent

Enumeration of possible context object watcher events:

  • Py_CONTEXT_SWITCHED: The current context has switched to a different context. The object passed to the watch callback is the now-current contextvars.Context object, or None if no context is current.

Added in version 3.14.

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

Context object watcher callback function. The object passed to the callback is event-specific; see PyContextEvent for details.

If the callback returns with an exception set, it must return -1; this exception will be printed as an unraisable exception using PyErr_FormatUnraisable(). Otherwise it should return 0.

There may already be a pending exception set on entry to the callback. In this case, the callback should return 0 with the same exception still set. This means the callback may not call any other API that can set an exception unless it saves and clears the exception state first, and restores it before returning.

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。