
:mod:`thread` --- マルチスレッドのコントロール
==============================================

.. module:: thread
   :synopsis: 1つのインタープリタの中でのマルチスレッド制御

.. note::
   Python 3.0 では :mod:`thread` モジュールは :mod:`_thread` に改名さ
   れました。
   :term:`2to3` ツールは、 3.0 コードへの変換時に、自動的に import 宣
   言を適合させます。しかしながら、上位の :mod:`threading` モジュール
   を使うことを検討して下さい。


.. index::
   single: light-weight processes
   single: processes, light-weight
   single: binary semaphores
   single: semaphores, binary

このモジュールはマルチスレッド (別名 :dfn:`軽量プロセス`
(:dfn:`light-weight processes`)または :dfn:`タスク` (:dfn:`tasks`)) に
用いられる低レベルプリミティブを提供します --- グローバルデータ空間を
共有するマルチスレッドを制御します。
同期のための単純なロック (別名 :dfn:`mutexes` またはバイナリセマフォ
(:dfn:`binary semaphores`))が提供されています。
:mod:`threading` モジュールは、このモジュール上で、より使い易く高級
なスレッディングの API　を提供します。

 .. index::
    single: pthreads
    pair: threads; POSIX

このモジュールはオプションです。 Windows, Linux, SGI IRIX, Solaris 2.x、
そして同じようなPOSIXスレッド (別名 "pthread" ) 実装のシステム上でサポー
トされます。 :mod:`thread`を使用することのできないシステムでは、
:mod:`dummy_thread` が用意されています。 :mod:`dummy_thread` はこのモ
ジュールと同じインターフェースを持ち、置き換えて使用することができます。

.. index::
   single: pthreads
   pair: threads; POSIX

定数と関数は以下のように定義されています:


.. exception:: error

   スレッド特有の例外です。


.. data:: LockType

   これはロックオブジェクトのタイプです。


.. function:: start_new_thread(function, args[, kwargs])

   新しいスレッドを開始して、そのIDを返します。スレッドは引数リスト
   *args* (タプルでなければなりません)の関数 *function* を実行します。
   オプション引数 *kwargs* はキーワード引数の辞書を指定します。関数が
   戻るとき、スレッドは黙って終了します。関数が未定義の例外でターミネー
   トしたとき、スタックトレースが表示され、そしてスレッドが終了します
   (しかし他のスレッドは走り続けます)。


.. function:: interrupt_main()

   メインスレッドで :exc:`KeyboardInterrupt` を送出します。サブスレッ
   ドはこの関数を使ってメインスレッドに割り込みをかけることができます。

   .. versionadded:: 2.3


.. function:: exit()

   :exc:`SystemExit` を送出します。それが捕えられないときは、黙っ
   てスレッドを終了させます。


.. function:: exit_prog(status)

   全てのスレッドを終了させ、整数の引き数 *status* をプログラム全体の
   終了コードとして返します。
   ** 警告 :** このスレッド、および、他のスレッドの :keyword:`finally`
   節の、未実行のプログラムは実行されません。


.. function:: allocate_lock()

   新しいロックオブジェクトを返します。ロックのメソッドはこの後に記述
   されます。ロックは初期状態としてアンロック状態です。


.. function:: get_ident()

   現在のスレッドの 'スレッドID' を返します。非ゼロの整数です。
   この値は直接の意味を持っていません;
   例えばスレッド特有のデータの辞書に索引をつけるためのような、マジッ
   ククッキーとして意図されています。スレッドが終了し、他のスレッドが
   作られたとき、スレッド ID は再利用されるかもしれません。


.. function:: stack_size([size])

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

   .. versionadded:: 2.5

ロックオブジェクトは次のようなメソッドを持っています:


.. method:: lock.acquire([waitflag])

   オプションの引数なしで使用すると、このメソッドは他のスレッドがロッ
   クしているかどうかにかかわらずロックを獲得します。
   ただし、他のスレッドがすでにロックしている場合には解除されるまで待っ
   てからロックを獲得します (同時にロックを獲得できるスレッドはひとつ
   だけであり、これこそがロックの存在理由です)。整数の引数 *waitflag*
   を指定すると、その値によって動作が変わります。引数が ``0`` のときは、
   待たずにすぐ獲得できる場合にだけロックを獲得します。 ``0`` 以外の値
   を与えると、先の例と同様、ロックの状態にかかわらず獲得をおこないま
   す。なお、ロックを獲得すると ``True`` 、できなかったときには
   ``False`` を返します。


.. method:: lock.release()

   ロックを解放します。そのロックは既に獲得されたものでなければなりま
   せんが、しかし同じスレッドによって獲得されたものである必要はありま
   せん。


.. method:: lock.locked()

   ロックの状態を返します: 同じスレッドによって獲得されたものなら
   ``True`` 、違うのなら ``False`` を返します。

これらのメソッドに加えて、ロックオブジェクトは :keyword:`with` 文を通
じて以下の例のように使うこともできます。 ::

   import thread

   a_lock = thread.allocate_lock()

   with a_lock:
       print "a_lock is locked while this executes"

** 警告: **

  .. index:: module: signal

* スレッドは割り込みと奇妙な相互作用をします: :exc:`KeyboardInterrupt`
  例外は任意のスレッドによって受け取られます。
  ( :mod:`signal` モジュールが利用可能なとき、割り込みは常にメインスレッ
  ドへ行きます。)

* :func:`sys.exit` を呼び出す、あるいは :exc:`SystemExit` 例外を送出す
  ることは、 :func:`exit` を呼び出すことと同じです。

* I/O待ちをブロックするかもしれない全ての組込み関数が、他のスレッドの
  走行を許すわけではありません。 (ほとんどの一般的なもの (
  :func:`time.sleep`, :meth:`file.read`, :func:`select.select`) は期待
  通りに働きます。)

* ロックの :meth:`acquire` メソッドに割り込むことはできません ---
  :exc:`KeyboardInterrupt` 例外は、ロックが獲得された後に発生します。

  .. index:: pair: threads; IRIX

* メインスレッドが終了したとき、他のスレッドが生き残るかどうかは、シス
  テムに依存します。ネイティブスレッド実装を使う SGI, IRIX では生き残り
  ます。
  その他の多くのシステムでは、 :keyword:`try` ... :keyword:`finally`
  節や、オブジェクトデストラクタを実行せずに終了されます。

* メインスレッドが終了したとき、それの通常のクリーンアップは行なわれず、
  (:keyword:`try` ... :keyword:`finally` 節が尊重されることは除きます)、
  標準 I/O ファイルはフラッシュされません。

