# 3 `threading` -- 高水準のスレッドインタフェース

このモジュールでは、高水準のスレッドインタフェースを より低水準な`thread` モジュールの上に構築しています。

また、`thread` がないために`threading` を使えないような 状況向けに`dummy_threading` を提供しています。

このモジュールでは以下のような関数とオブジェクトを定義しています:

`activeCount`( | )

  現在のアクティブな`Thread`オブジェクトの数を返します。 この数は `enumerate()` の返すリストの長さと同じです。

`Condition`( | )

  新しい条件変数 (condition variable) オブジェクトを返すファクトリ関数です。 条件変数を使うと、ある複数のスレッドを別のスレッドの通知があるまで 待機させられます。

`currentThread`( | )

  関数を呼び出している処理のスレッドに対応する `Thread` オブジェクトを 返します。関数を呼び出している処理のスレッドが `threading` モジュール で生成したものでない場合、限定的な機能しかもたないダミースレッドオブジェクト を返します。

`enumerate`( | )

  現在アクティブな `Thread` オブジェクト全てのリストを返します。 リストには、デーモンスレッド (daemonic thread)、 `currentThread()` の生成するダミースレッドオブジェクト、 そして主スレッドが入ります。終了したスレッドとまだ開始していないスレッド は入りません。

`Event`( | )

  新たなイベントオブジェクトを返すファクトリ関数です。 イベントは `set()` メソッドを使うと `True` に、 `clear()` メソッドを使うと `False` にセットされるような フラグを管理します。`wait()` メソッドは、全てのフラグが 真になるまでブロックするようになっています。

class `local`
  スレッドローカルデータ (thread-local data) を表現するためのクラスです。 スレッドローカルデータとは、値が各スレッド固有になるようなデータです。 スレッドローカルデータを管理するには、`local` (または`local` のサブクラス) のインスタンスを作成して、その属性に値を代入します:

      mydata = threading.local()
      mydata.x = 1

  インスタンスの値はスレッドごとに違った値になります。

  詳細と例題については、 `_threading_local` モジュールのドキュメンテーション文字列を 参照してください。

  バージョン 2.4 で 新たに追加 された仕様です。

`Lock`( | )

  新しいプリミティブロック (primitive lock) オブジェクトを返すファクトリ 関数です。 スレッドが一度プリミティブロックを獲得すると、それ以後のロック獲得の試みは ロックが解放されるまでブロックします。どのスレッドでもロックを解放できます。

`RLock`( | )

  新しい再入可能ロックオブジェクトを返すファクトリ関数です。 再入可能ロックはそれを獲得したスレッドによって解放されなければなりません。 いったんスレッドが再入可能ロックを獲得すると、 同じスレッドはブロックされずにもう一度それを獲得できます; そのスレッドは獲得した回数だけ解放しなければいけません。

`Semaphore`( | [value])

  新しいセマフォ (semaphore) オブジェクトを返すファクトリ関数です。 セマフォは、`release()`を呼び出した数から`acquire()` を呼び出した数を引き、初期値を足した値を表すカウンタを管理します。 `acquire()`メソッドは、カウンタの値を負にせずに処理を戻せるまで 必要ならば処理をブロックします。 value を指定しない場合、デフォルトの値は 1 になります。

`BoundedSemaphore`( | [value])

  新しい有限セマフォ (bounded semaphore) オブジェクトを返す ファクトリ関数です。有限セマフォは、現在の値が初期値を超過しないよう チェックを行います。超過を起こした場合、`ValueError` を 送出します。たいていの場合、セマフォは限られた容量のリソースを 保護するために使われるものです。従って、あまりにも頻繁なセマフォの解放は バグが生じているしるしです。 value を指定しない場合、デフォルトの値は 1 になります。

class `Thread`
  処理中のスレッドを表すクラスです。 このクラスは制限のある範囲内で安全にサブクラス化できます。

class `Timer`
  指定時間経過後に関数を実行するスレッドです。

`settrace`( | func)

  `threading` モジュールを使って開始した全てのスレッドに トレース関数 を設定します。 func は各スレッドの`run()` を呼び出す前に スレッドの`sys.settrace()` に渡されます。 バージョン 2.3 で 新たに追加 された仕様です。

`setprofile`( | func)

  `threading` モジュールを使って開始した全てのスレッドに プロファイル関数 を設定します。 func は各スレッドの`run()` を呼び出す前に スレッドの`sys.settrace()` に渡されます。 バージョン 2.3 で 新たに追加 された仕様です。

`stack_size`( | [size])

  新しいスレッドが作られる際に使われるスレッドのスタックサイズを返します。 オプションの size 引数は次に作られるスレッドに対する スタックサイズを指定するものですが、0 (プラットフォームまたは設定されたデフォルト) または少なくとも 32,768 (32kB) であるような正の整数でなければなりません。 もしスタックサイズの変更がサポートされていなければ `ThreadError` が送出されます。また指定されたスタックサイズが条件を満たしていなければ `ValueError` が送出されスタックサイズは変更されないままになります。 32kB は今のところインタプリタ自体に十分なスタックスペースを保証するための値として サポートされる最小のスタックサイズです。プラットフォームによってはスタックサイズの 値に固有の制限が課されることもあります。たとえば 32kB より大きな最小スタックサイズを 要求されたり、システムメモリサイズの倍数の割り当てを要求されるなどです - より 詳しい情報はプラットフォームごとの文書で確認してください(4kB ページは一般的ですので、 情報が見当たらないときには 4096 の倍数を指定しておくといいかもしれません)。 利用可能: Windows, POSIX スレッドのあるシステム。 バージョン 2.5 で 新たに追加 された仕様です。

オブジェクトの詳細なインターフェースを以下に説明します。

このモジュールのおおまかな設計は Java のスレッドモデルに基づいています。 とはいえ、Java がロックと条件変数を全てのオブジェクトの基本的な挙動に しているのに対し、 Python ではこれらを別個のオブジェクトに分けています。 Python の `Thread` クラスがサポートしているのは Java の Thread クラスの挙動のサブセットにすぎません; 現状では、優先度 (priority)や スレッドグループがなく、スレッドの破壊 (destroy)、中断 (stop)、 一時停止 (suspend)、復帰 (resume)、割り込み (interrupt) は行えません。 Java の Thread クラスにおける静的メソッドに対応する機能が実装されている 場合には、、モジュールレベルの関数になっています。

以下に説明するメソッドは全て原子的 (atomic) に実行されます。