情境變數物件（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"。

情境變數函式：

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