スレッドローカルストレージのサポート
************************************

Python インタープリタは、基盤となるネイティブの TLS 実装をラップした低
水準のスレッドローカルストレージ (TLS) を提供し、 Python レベルのスレ
ッドローカルストレージ API ("threading.local") を支えます。 CPython の
C レベルの API は pthreads や Windows が提供するものと似ており、スレッ
ドキーと関数を使って、スレッドごとに void* 値を関連付けます。

これらの関数は独自にロックを行うため、呼び出す際に *スレッド状態* が *
アタッチされている* 必要は *ありません*。

"Python.h" は TLS API の宣言を include せず、スレッドローカルストレー
ジを使うには "pythread.h" を include する必要があることに注意してくだ
さい。

注釈:

  この API 関数はどれも void* 値の代わりにメモリ管理を行うことはしませ
  ん。 メモリの確保と解放は自前で行う必要があります。 void* 値がたまた
  ま PyObject* だった場合は、 API 関数はそれぞれの値の参照カウントの操
  作は行いません。


スレッド固有ストレージ API
==========================

スレッド固有ストレージ (TSS) API は、CPython インタープリタ内で使われ
ていた TLS API を置き換えるために導入されました。 スレッドキーの表現に
は int ではなく、新しい型 "Py_tss_t" を使います。

Added in version 3.7.

参考: "CPython のスレッドローカルストレージのための新しい C API" (**PEP
    539**)

type Py_tss_t

   このデータ構造体はスレッドキーの状態を表現しています。この構造体の
   定義は、根底の TLS 実装に依存し、キーの初期化状態を表現する内部フィ
   ールドを持ちます。 この構造体には公開 (public) のメンバはありません
   。

   Py_LIMITED_API が定義されていないときは、この型の
   "Py_tss_NEEDS_INIT" による静的メモリ確保ができます。

Py_tss_NEEDS_INIT

   このマクロは "Py_tss_t" 変数の初期化子に展開されます。 このマクロは
   Py_LIMITED_API があるときは定義されません。


動的なメモリ確保
================

動的な "Py_tss_t" のメモリ確保は Py_LIMITED_API でビルドされた拡張モジ
ュールで必要になりますが、その実装がビルド時に不透明なために、この型の
静的なメモリ確保は不可能です。

Py_tss_t *PyThread_tss_alloc()
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   "Py_tss_NEEDS_INIT" で初期化した値と同じ状態の値を返します。 動的な
   メモリ確保に失敗した場合は "NULL" を返します。

void PyThread_tss_free(Py_tss_t *key)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   まず "PyThread_tss_delete()" を呼んで、関連付けられたスレッドローカ
   ルな値との対応を解除してから、 "PyThread_tss_alloc()" で確保した
   *key* を解放します。 *key* 引数が "NULL" の場合は何もしません。

   注釈:

     解放したキーはダングリングポインタになります。 キーを "NULL" に設
     定し直してください。


メソッド
========

これらの関数の引数 *key* は "NULL" であってはなりません。 また、指定さ
れた "Py_tss_t" を "PyThread_tss_create()" で初期化していなければ、
"PyThread_tss_set()" と "PyThread_tss_get()" の動作は未定義です。

int PyThread_tss_is_created(Py_tss_t *key)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   指定された "Py_tss_t" が "PyThread_tss_create()" で初期化されていれ
   ば、0 以外の値を返します。

int PyThread_tss_create(Py_tss_t *key)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   TSS キーの初期化に成功すると 0 を返します。 *key* 引数が指す値を
   "Py_tss_NEEDS_INIT" で初期化していなければ、動作は未定義です。 同じ
   キーに対して繰り返し呼び出せます。 初期化済みのキーに対しては何もせ
   ず、即座に成功を返します。

void PyThread_tss_delete(Py_tss_t *key)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   TSS キーを破棄し、すべてのスレッドでそのキーに関連付けられた値との
   対応を解除して、キーを未初期化の状態にします。 破棄したキーは
   "PyThread_tss_create()" で再び初期化できます。 同じキーに対して繰り
   返し呼び出せます。 破棄済みのキーに対しては何もしません。

int PyThread_tss_set(Py_tss_t *key, void *value)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   現在のスレッドで void* 値を TSS キーに関連付けることに成功すると、0
   を返します。 キーから void* 値への対応付けは、スレッドごとに独立し
   ています。

void *PyThread_tss_get(Py_tss_t *key)
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   現在のスレッドで TSS キーに関連付けられている void* 値を返します。
   現在のスレッドでそのキーに値が関連付けられていなければ、"NULL" を返
   します。


従来の API
==========

バージョン 3.7 で非推奨: この API は スレッド固有ストレージ (TSS) API
に置き換えられました。

注釈:

  このバージョンの API は、ネイティブの TLS キーを安全に "int" へキャ
  ストできないプラットフォームをサポートしません。 そのようなプラット
  フォームでは、"PyThread_create_key()" は即座に失敗を示す値を返し、そ
  の他の TLS 関数はすべて何もしません。

前述の互換性の問題により、このバージョンのAPIは新規のコードで利用すべ
きではありません。

int PyThread_create_key()
    * 次に属します: Stable ABI.*

void PyThread_delete_key(int key)
    * 次に属します: Stable ABI.*

int PyThread_set_key_value(int key, void *value)
    * 次に属します: Stable ABI.*

void *PyThread_get_key_value(int key)
    * 次に属します: Stable ABI.*

void PyThread_delete_key_value(int key)
    * 次に属します: Stable ABI.*

void PyThread_ReInitTLS()
    * 次に属します: Stable ABI.*
