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

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"。
