Thread-local storage support
****************************

The Python interpreter provides low-level support for thread-local
storage (TLS) which wraps the underlying native TLS implementation to
support the Python-level thread-local storage API ("threading.local").
The CPython C level APIs are similar to those offered by pthreads and
Windows: use a thread key and functions to associate a void* value per
thread.

A *thread state* does *not* need to be *attached* when calling these
functions; they supply their own locking.

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

注釈:

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


Thread-specific storage API
===========================

The thread-specific storage (TSS) API was introduced to supersede the
use of the existing TLS API within the CPython interpreter.  This API
uses a new type "Py_tss_t" instead of int to represent thread keys.

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 があるときは定義されません。


Dynamic allocation
==================

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

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

   Return a value which is the same state as a value initialized with
   "Py_tss_NEEDS_INIT", or "NULL" in the case of dynamic allocation
   failure.

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

   Free the given *key* allocated by "PyThread_tss_alloc()", after
   first calling "PyThread_tss_delete()" to ensure any associated
   thread locals have been unassigned. This is a no-op if the *key*
   argument is "NULL".

   注釈:

     A freed key becomes a dangling pointer. You should reset the key
     to "NULL".


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

The parameter *key* of these functions must not be "NULL".  Moreover,
the behaviors of "PyThread_tss_set()" and "PyThread_tss_get()" are
undefined if the given "Py_tss_t" has not been initialized by
"PyThread_tss_create()".

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

   Return a non-zero value if the given "Py_tss_t" has been
   initialized by "PyThread_tss_create()".

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

   Return a zero value on successful initialization of a TSS key.  The
   behavior is undefined if the value pointed to by the *key* argument
   is not initialized by "Py_tss_NEEDS_INIT".  This function can be
   called repeatedly on the same key -- calling it on an already
   initialized key is a no-op and immediately returns success.

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

   Destroy a TSS key to forget the values associated with the key
   across all threads, and change the key's initialization state to
   uninitialized.  A destroyed key is able to be initialized again by
   "PyThread_tss_create()". This function can be called repeatedly on
   the same key -- calling it on an already destroyed key is a no-op.

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

   Return a zero value to indicate successfully associating a void*
   value with a TSS key in the current thread.  Each thread has a
   distinct mapping of the key to a void* value.

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

   Return the void* value associated with a TSS key in the current
   thread.  This returns "NULL" if no value is associated with the key
   in the current thread.


Legacy APIs
===========

バージョン 3.7 で非推奨: This API is superseded by the thread-specific
storage (TSS) API.

注釈:

  This version of the API does not support platforms where the native
  TLS key is defined in a way that cannot be safely cast to "int".  On
  such platforms, "PyThread_create_key()" will return immediately with
  a failure status, and the other TLS functions will all be no-ops on
  such platforms.

前述の互換性の問題により、このバージョンの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.*
