上下文变量对象
**************

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)

   注册 *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"。
