情境變數物件（Context Variables Objects）
*****************************************

在 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

   代表 *情境變數* 型別的型別物件。

PyTypeObject PyContextToken_Type

   代表 *情境變數 token* 型別的型別物件。

型別檢查巨集：

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_New(void)
    *回傳值：新的參照。*

   建立一個新的空的情境物件。 如果發生錯誤，則回傳 "NULL"。

PyObject *PyContext_Copy(PyObject *ctx)
    *回傳值：新的參照。*

   建立傳入的 *ctx* 情境物件的淺層複製 (shallow copy)。如果發生錯誤，
   則回傳 "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.

   在 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.)

   在 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.

   在 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.

   在 3.14 版被加入.

情境變數函式：

PyObject *PyContextVar_New(const char *name, PyObject *def)
    *回傳值：新的參照。*

   建立一個新的 "ContextVar" 物件。*name* 參數用於自我檢查（
   introspection）和除錯目的。*def* 參數指定情境變數的預設值，亦可用
   "NULL" 表示沒有預設值。 如果發生錯誤，此函式會回傳 "NULL"。

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

   取得情境變數的值。如果在查找過程中發生錯誤則回傳 "-1"，如果沒有發生
   錯誤則無論是否找到值都會回傳 "0"。

   如果找到情境變數，*value* 將會是指向它的指標。如果 *沒有* 找到情境
   變數，*value* 將會指到：

   * *default_value* 預設值，但前提是預設值不是 "NULL"；

   * *var* 的預設值，但前提是預設值不是 "NULL"；

   * "NULL"

   除了 "NULL" 之外，此函式會回傳一個新的參照（reference）。

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
    *回傳值：新的參照。*

   在目前的情境中將 *var* 的值設為 *value*。會回傳一個用來代表此變更的
   新 token 物件，如果發生錯誤則回傳 "NULL"。

int PyContextVar_Reset(PyObject *var, PyObject *token)

   將 *var* 情境變數的狀態設回之前的狀態，亦即上一次回傳 token 的
   "PyContextVar_Set()" 被呼叫前的狀態。此函式在成功時回傳 "0"，錯誤時
   回傳 "-1"。
