コンテキスト変数オブジェクト
****************************

Added in version 3.7.

バージョン 3.7.1 で変更:

注釈:

  Python 3.7.1 で全てのコンテキスト変数の C API のシグネチャは、
  "PyContext", "PyContextVar", "PyContextToken" の代わりに "PyObject"
  ポインタを使うように **変更** されました。例えば:

     // in 3.7.0:
     PyContext *PyContext_New(void);

     // in 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

   *コンテキスト* 型を表現する型オブジェクト。

PyTypeObject PyContextVar_Type

   *コンテキスト変数* 型を表現する型オブジェクト。

PyTypeObject PyContextToken_Type

   *コンテキスト変数トークン* 型を表現する型オブジェクト。

型チェックマクロ:

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* コンテキストを無効にし、1 つ前のコンテキストを現在のスレッド
   の現在のコンテキストに復元します。 成功したら "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*
   が指すものは次のようになっています:

   * ("NULL" でなければ) *default_value*

   * ("NULL" でなければ) *var* のデフォルト値

   * "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" を返します。
