"threading" — Higher-level threading interface
**********************************************

**ソースコード:** Lib/threading.py

======================================================================

This module constructs higher-level threading interfaces on top of the
lower level "thread" module. See also the "mutex" and "Queue" modules.

The "dummy_threading" module is provided for situations where
"threading" cannot be used because "thread" is missing.

注釈: Starting with Python 2.6, this module provides **PEP 8**
  compliant aliases and properties to replace the "camelCase" names
  that were inspired by Java’s threading API. This updated API is
  compatible with that of the "multiprocessing" module. However, no
  schedule has been set for the deprecation of the "camelCase" names
  and they remain fully supported in both Python 2.x and 3.x.

注釈: Starting with Python 2.5, several Thread methods raise
  "RuntimeError" instead of "AssertionError" if called erroneously.

**CPython implementation detail:** In CPython, due to the *Global
Interpreter Lock*, only one thread can execute Python code at once
(even though certain performance-oriented libraries might overcome
this limitation). If you want your application to make better use of
the computational resources of multi-core machines, you are advised to
use "multiprocessing". However, threading is still an appropriate
model if you want to run multiple I/O-bound tasks simultaneously.

This module defines the following functions and objects:

threading.active_count()
threading.activeCount()

   生存中の "Thread" オブジェクトの数を返します。この数は
   "enumerate()" の返すリストの長さと同じです。

   バージョン 2.6 で変更: Added "active_count()" spelling.

threading.Condition()

   A factory function that returns a new condition variable object. A
   condition variable allows one or more threads to wait until they
   are notified by another thread.

   See Condition オブジェクト.

threading.current_thread()
threading.currentThread()

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

   バージョン 2.6 で変更: Added "current_thread()" spelling.

threading.enumerate()

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

threading.Event()

   A factory function that returns a new event object.  An event
   manages a flag that can be set to true with the "set()" method and
   reset to false with the "clear()" method.  The "wait()" method
   blocks until the flag is true.

   See Event オブジェクト.

class threading.local

   A class that represents thread-local data.  Thread-local data are
   data whose values are thread specific.  To manage thread-local
   data, just create an instance of "local" (or a subclass) and store
   attributes on it:

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

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

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

   バージョン 2.4 で追加.

threading.Lock()

   A factory function that returns a new primitive lock object.  Once
   a thread has acquired it, subsequent attempts to acquire it block,
   until it is released; any thread may release it.

   See Lock オブジェクト.

threading.RLock()

   A factory function that returns a new reentrant lock object. A
   reentrant lock must be released by the thread that acquired it.
   Once a thread has acquired a reentrant lock, the same thread may
   acquire it again without blocking; the thread must release it once
   for each time it has acquired it.

   See RLock オブジェクト.

threading.Semaphore([value])

   A factory function that returns a new semaphore object.  A
   semaphore manages a counter representing the number of "release()"
   calls minus the number of "acquire()" calls, plus an initial value.
   The "acquire()" method blocks if necessary until it can return
   without making the counter negative.  If not given, *value*
   defaults to 1.

   See Semaphore オブジェクト.

threading.BoundedSemaphore([value])

   A factory function that returns a new bounded semaphore object.  A
   bounded semaphore checks to make sure its current value doesn’t
   exceed its initial value.  If it does, "ValueError" is raised. In
   most situations semaphores are used to guard resources with limited
   capacity.  If the semaphore is released too many times it’s a sign
   of a bug.  If not given, *value* defaults to 1.

class threading.Thread

   A class that represents a thread of control.  This class can be
   safely subclassed in a limited fashion.

   See Thread オブジェクト.

class threading.Timer

   A thread that executes a function after a specified interval has
   passed.

   See Timer オブジェクト.

threading.settrace(func)

   "threading" モジュールを使って開始した全てのスレッドにトレース関数
   を設定します。 *func* は各スレッドの "run()" を呼び出す前にスレッド
   の "sys.settrace()" に渡されます。

   バージョン 2.3 で追加.

threading.setprofile(func)

   "threading" モジュールを使って開始した全てのスレッドにプロファイル
   関数を設定します。 *func* は各スレッドの "run()" を呼び出す前にスレ
   ッドの "sys.setprofile()" に渡されます。

   バージョン 2.3 で追加.

threading.stack_size([size])

   Return the thread stack size used when creating new threads.  The
   optional *size* argument specifies the stack size to be used for
   subsequently created threads, and must be 0 (use platform or
   configured default) or a positive integer value of at least 32,768
   (32 KiB). If *size* is not specified, 0 is used.  If changing the
   thread stack size is unsupported, a "ThreadError" is raised.  If
   the specified stack size is invalid, a "ValueError" is raised and
   the stack size is unmodified.  32kB is currently the minimum
   supported stack size value to guarantee sufficient stack space for
   the interpreter itself.  Note that some platforms may have
   particular restrictions on values for the stack size, such as
   requiring a minimum stack size > 32kB or requiring allocation in
   multiples of the system memory page size - platform documentation
   should be referred to for more information (4kB pages are common;
   using multiples of 4096 for the stack size is the suggested
   approach in the absence of more specific information).
   Availability: Windows, systems with POSIX threads.

   バージョン 2.5 で追加.

exception threading.ThreadError

   Raised for various threading-related errors as described below.
   Note that many interfaces use "RuntimeError" instead of
   "ThreadError".

Detailed interfaces for the objects are documented below.

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

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


Thread オブジェクト
===================

This class represents an activity that is run in a separate thread of
control. There are two ways to specify the activity: by passing a
callable object to the constructor, or by overriding the "run()"
method in a subclass.  No other methods (except for the constructor)
should be overridden in a subclass.  In other words,  *only*  override
the "__init__()" and "run()" methods of this class.

Once a thread object is created, its activity must be started by
calling the thread’s "start()" method.  This invokes the "run()"
method in a separate thread of control.

Once the thread’s activity is started, the thread is considered 『
alive』. It stops being alive when its "run()" method terminates –
either normally, or by raising an unhandled exception.  The
"is_alive()" method tests whether the thread is alive.

Other threads can call a thread’s "join()" method.  This blocks the
calling thread until the thread whose "join()" method is called is
terminated.

A thread has a name.  The name can be passed to the constructor, and
read or changed through the "name" attribute.

A thread can be flagged as a 「daemon thread」.  The significance of
this flag is that the entire Python program exits when only daemon
threads are left.  The initial value is inherited from the creating
thread.  The flag can be set through the "daemon" property.

注釈: デーモンスレッドは終了時にいきなり停止されます。デーモンスレッ
  ドで使 われたリソース (開いているファイル、データベースのトランザク
  ションな ど) は適切に解放されないかもしれません。きちんと
  (gracefully) スレッ ドを停止したい場合は、スレッドを非デーモンスレッ
  ドにして、"Event" の ような適切なシグナル送信機構を使用してください
  。

スレッドには 「主スレッド (main thread)」 オブジェクトがあります。主ス
レッドは Python プログラムを最初に制御していたスレッドです。主スレッド
はデーモンスレッドではありません。

There is the possibility that 「dummy thread objects」 are created.
These are thread objects corresponding to 「alien threads」, which are
threads of control started outside the threading module, such as
directly from C code.  Dummy thread objects have limited
functionality; they are always considered alive and daemonic, and
cannot be "join()"ed.  They are never deleted, since it is impossible
to detect the termination of alien threads.

class threading.Thread(group=None, target=None, name=None, args=(), kwargs={})

   コンストラクタは常にキーワード引数を使って呼び出さなければなりませ
   ん。各引数は以下の通りです:

   *group* は "None" でなければなりません。将来 "ThreadGroup" クラスが
   実装されたときの拡張用に予約されている引数です。

   *target* は "run()" メソッドによって起動される呼び出し可能オブジェ
   クトです。デフォルトでは何も呼び出さないことを示す "None" になって
   います。

   *name* はスレッドの名前です。デフォルトでは、 *N* を小さな 10 進数
   として、 「Thread- *N*」 という形式の一意な名前を生成します。

   *args* は *target* を呼び出すときの引数タプルです。デフォルトは
   "()" です。

   *kwargs* は *target* を呼び出すときのキーワード引数の辞書です。デフ
   ォルトは "{}" です。

   サブクラスでコンストラクタをオーバライドした場合、必ずスレッドが何
   かを始める前に基底クラスのコンストラクタ ("Thread.__init__()") を呼
   び出しておかなくてはなりません。

   start()

      スレッドの活動を開始します。

      It must be called at most once per thread object.  It arranges
      for the object’s "run()" method to be invoked in a separate
      thread of control.

      同じスレッドオブジェクトに対し、このメソッドを2回以上呼び出した
      場合、 "RuntimeError" を送出します。

   run()

      スレッドの活動をもたらすメソッドです。

      このメソッドはサブクラスでオーバライドできます。標準の "run()"
      メソッドでは、オブジェクトのコンストラクタの *target* 引数に呼び
      出し可能オブジェクトを指定した場合、 *args* および *kwargs* の引
      数列およびキーワード引数とともに呼び出します。

   join([timeout])

      Wait until the thread terminates. This blocks the calling thread
      until the thread whose "join()" method is called terminates –
      either normally or through an unhandled exception – or until the
      optional timeout occurs.

      When the *timeout* argument is present and not "None", it should
      be a floating point number specifying a timeout for the
      operation in seconds (or fractions thereof). As "join()" always
      returns "None", you must call "isAlive()" after "join()" to
      decide whether a timeout happened – if the thread is still
      alive, the "join()" call timed out.

      *timeout* が指定されないかまたは "None" であるときは、この操作は
      スレッドが終了するまでブロックします。

      A thread can be "join()"ed many times.

      "join()" raises a "RuntimeError" if an attempt is made to join
      the current thread as that would cause a deadlock. It is also an
      error to "join()" a thread before it has been started and
      attempts to do so raises the same exception.

   name

      識別のためにのみ用いられる文字列です。名前には機能上の意味づけ
      (semantics) はありません。複数のスレッドに同じ名前をつけてもかま
      いません。名前の初期値はコンストラクタで設定されます。

      バージョン 2.6 で追加.

   getName()
   setName()

      Pre-2.6 API for "name".

   ident

      The 『thread identifier』 of this thread or "None" if the thread
      has not been started.  This is a nonzero integer.  See the
      "thread.get_ident()" function.  Thread identifiers may be
      recycled when a thread exits and another thread is created.  The
      identifier is available even after the thread has exited.

      バージョン 2.6 で追加.

   is_alive()
   isAlive()

      スレッドが生存中かどうかを返します。

      This method returns "True" just before the "run()" method starts
      until just after the "run()" method terminates.  The module
      function "enumerate()" returns a list of all alive threads.

      バージョン 2.6 で変更: Added "is_alive()" spelling.

   daemon

      A boolean value indicating whether this thread is a daemon
      thread (True) or not (False).  This must be set before "start()"
      is called, otherwise "RuntimeError" is raised.  Its initial
      value is inherited from the creating thread; the main thread is
      not a daemon thread and therefore all threads created in the
      main thread default to "daemon" = "False".

      デーモンでない生存中のスレッドが全てなくなると、 Python プログラ
      ム全体が終了します。

      バージョン 2.6 で追加.

   isDaemon()
   setDaemon()

      Pre-2.6 API for "daemon".


Lock オブジェクト
=================

A primitive lock is a synchronization primitive that is not owned by a
particular thread when locked.  In Python, it is currently the lowest
level synchronization primitive available, implemented directly by the
"thread" extension module.

A primitive lock is in one of two states, 「locked」 or 「unlocked」.
It is created in the unlocked state.  It has two basic methods,
"acquire()" and "release()".  When the state is unlocked, "acquire()"
changes the state to locked and returns immediately.  When the state
is locked, "acquire()" blocks until a call to "release()" in another
thread changes it to unlocked, then the "acquire()" call resets it to
locked and returns.  The "release()" method should only be called in
the locked state; it changes the state to unlocked and returns
immediately. If an attempt is made to release an unlocked lock, a
"ThreadError" will be raised.

When more than one thread is blocked in "acquire()" waiting for the
state to turn to unlocked, only one thread proceeds when a "release()"
call resets the state to unlocked; which one of the waiting threads
proceeds is not defined, and may vary across implementations.

全てのメソッドはアトミックに実行されます。

Lock.acquire([blocking])

   ブロックあり、またはブロックなしでロックを獲得します。

   引数 *blocking* を "True" (デフォルト) に設定して呼び出した場合、ロ
   ックがアンロック状態になるまでブロックします。そしてそれをロック状
   態にしてから "True" を返します。

   引数 *blocking* の値を "False" にして呼び出すとブロックしません。
   *blocking* を "True" にして呼び出した場合にブロックするような状況で
   は、直ちに "False" を返します。それ以外の場合には、ロックをロック状
   態にして "True" を返します。

Lock.release()

   Release a lock.

   ロックの状態がロックのとき、状態をアンロックにリセットして処理を戻
   します。他のスレッドがロックがアンロック状態になるのを待ってブロッ
   クしている場合、ただ一つのスレッドだけが処理を継続できるようにしま
   す。

   When invoked on an unlocked lock, a "ThreadError" is raised.

   戻り値はありません。


RLock オブジェクト
==================

再入可能ロック (reentrant lock) とは、同じスレッドが複数回獲得できるよ
うな同期プリミティブです。再入可能ロックの内部では、プリミティブロック
の使うロック／アンロック状態に加え、 「所有スレッド (owning thread)」
と 「再帰レベル (recursion level)」 という概念を用いています。ロック状
態では何らかのスレッドがロックを所有しており、アンロック状態ではいかな
るスレッドもロックを所有していません。

To lock the lock, a thread calls its "acquire()" method; this returns
once the thread owns the lock.  To unlock the lock, a thread calls its
"release()" method. "acquire()"/"release()" call pairs may be nested;
only the final "release()" (the "release()" of the outermost pair)
resets the lock to unlocked and allows another thread blocked in
"acquire()" to proceed.

RLock.acquire([blocking=1])

   ブロックあり、またはブロックなしでロックを獲得します。

   引数なしで呼び出した場合: スレッドが既にロックを所有している場合、
   再帰レベルをインクリメントして即座に処理を戻します。それ以外の場合
   、他のスレッドがロックを所有していれば、そのロックの状態がアンロッ
   クになるまでブロックします。その後、ロックの状態がアンロックになる
   (いかなるスレッドもロックを所有しない状態になる) と、ロックの所有権
   を獲得し、再帰レベルを 1 にセットして処理を戻します。ロックの状態が
   アンロックになるのを待っているスレッドが複数ある場合、その中の一つ
   だけがロックの所有権を獲得できます。この場合、戻り値はありません。

   引数 *blocking* の値を true にして呼び出した場合、引数なしで呼び出
   したときと同じことを行ない、true を返します。

   引数 *blocking* の値を false にして呼び出すとブロックしません。引数
   なしで呼び出した場合にブロックするような状況であった場合には直ちに
   false を返します。それ以外の場合には、引数なしで呼び出したときと同
   じ処理を行い true を返します。

RLock.release()

   再帰レベルをデクリメントしてロックを解放します。デクリメント後に再
   帰レベルがゼロになった場合、ロックの状態をアンロック (いかなるスレ
   ッドにも所有されていない状態) にリセットし、ロックの状態がアンロッ
   クになるのを待ってブロックしているスレッドがある場合にはその中のた
   だ一つだけが処理を進行できるようにします。デクリメント後も再帰レベ
   ルがゼロでない場合、ロックの状態はロックのままで、呼び出し側のスレ
   ッドに所有されたままになります。

   呼び出し側のスレッドがロックを所有しているときにのみこのメソッドを
   呼び出してください。ロックの状態がアンロックの時にこのメソッドを呼
   び出すと、 "RuntimeError" が送出されます。

   戻り値はありません。


Condition オブジェクト
======================

A condition variable is always associated with some kind of lock; this
can be passed in or one will be created by default.  (Passing one in
is useful when several condition variables must share the same lock.)

A condition variable has "acquire()" and "release()" methods that call
the corresponding methods of the associated lock. It also has a
"wait()" method, and "notify()" and "notifyAll()" methods.  These
three must only be called when the calling thread has acquired the
lock, otherwise a "RuntimeError" is raised.

The "wait()" method releases the lock, and then blocks until it is
awakened by a "notify()" or "notifyAll()" call for the same condition
variable in another thread.  Once awakened, it re-acquires the lock
and returns.  It is also possible to specify a timeout.

The "notify()" method wakes up one of the threads waiting for the
condition variable, if any are waiting.  The "notifyAll()" method
wakes up all threads waiting for the condition variable.

Note: the "notify()" and "notifyAll()" methods don’t release the lock;
this means that the thread or threads awakened will not return from
their "wait()" call immediately, but only when the thread that called
"notify()" or "notifyAll()" finally relinquishes ownership of the
lock.

Tip: the typical programming style using condition variables uses the
lock to synchronize access to some shared state; threads that are
interested in a particular change of state call "wait()" repeatedly
until they see the desired state, while threads that modify the state
call "notify()" or "notifyAll()" when they change the state in such a
way that it could possibly be a desired state for one of the waiters.
For example, the following code is a generic producer-consumer
situation with unlimited buffer capacity:

   # Consume one item
   cv.acquire()
   while not an_item_is_available():
       cv.wait()
   get_an_available_item()
   cv.release()

   # Produce one item
   cv.acquire()
   make_an_item_available()
   cv.notify()
   cv.release()

To choose between "notify()" and "notifyAll()", consider whether one
state change can be interesting for only one or several waiting
threads.  E.g. in a typical producer-consumer situation, adding one
item to the buffer only needs to wake up one consumer thread.

class threading.Condition([lock])

   *lock* を指定して、 "None" の値にする場合、 "Lock" または "RLock"
   オブジェクトでなければなりません。この場合、 *lock* は根底にあるロ
   ックオブジェクトとして使われます。それ以外の場合には新しい "RLock"
   オブジェクトを生成して使います。

   acquire(*args)

      根底にあるロックを獲得します。このメソッドは根底にあるロックの対
      応するメソッドを呼び出します。そのメソッドの戻り値を返します。

   release()

      根底にあるロックを解放します。このメソッドは根底にあるロックの対
      応するメソッドを呼び出します。戻り値はありません。

   wait([timeout])

      通知 (notify) を受けるか、タイムアウトするまで待機します。呼び出
      し側のスレッドがロックを獲得していないときにこのメソッドを呼び出
      すと "RuntimeError" が送出されます。

      This method releases the underlying lock, and then blocks until
      it is awakened by a "notify()" or "notifyAll()" call for the
      same condition variable in another thread, or until the optional
      timeout occurs.  Once awakened or timed out, it re-acquires the
      lock and returns.

      *timeout* 引数を指定して、 "None" 以外の値にする場合、タイムアウ
      トを秒 (または端数秒) を表す浮動小数点数でなければなりません。

      根底にあるロックが "RLock" である場合、 "release()" メソッドでは
      ロックは解放されません。というのも、ロックが再帰的に複数回獲得さ
      れている場合には、 "release()" によって実際にアンロックが行われ
      ないかもしれないからです。その代わり、ロックが再帰的に複数回獲得
      されていても確実にアンロックを行える "RLock" クラスの内部インタ
      フェースを使います。その後ロックを再獲得する時に、もう一つの内部
      インタフェースを使ってロックの再帰レベルを復帰します。

   notify(n=1)

      デフォルトで、この条件変数を待っている1つのスレッドを起こします
      。 呼び出し側のスレッドがロックを獲得していないときにこのメソッ
      ドを呼び出すと "RuntimeError" が送出されます。

      何らかの待機中スレッドがある場合、そのうち *n* スレッドを起こし
      ます。待機中のスレッドがなければ何もしません。

      現在の実装では、少なくとも *n* スレッドが待機中であれば、ちょう
      ど *n* スレッドを起こします。とはいえ、この挙動に依存するのは安
      全ではありません。将来、実装の最適化によって、複数のスレッドを起
      こすようになるかもしれないからです。

      注意: 起こされたスレッドは実際にロックを再獲得できるまで
      "wait()" 呼び出しから戻りません。 "notify()" はロックを解放しな
      いので、 "notify()" 呼び出し側は明示的にロックを解放しなければな
      りません。

   notify_all()
   notifyAll()

      この条件を待っているすべてのスレッドを起こします。このメソッドは
      "notify()" のように動作しますが、 1 つではなくすべての待ちスレッ
      ドを起こします。呼び出し側のスレッドがロックを獲得していない場合
      、 "RuntimeError" が送出されます。

      バージョン 2.6 で変更: Added "notify_all()" spelling.


Semaphore オブジェクト
======================

This is one of the oldest synchronization primitives in the history of
computer science, invented by the early Dutch computer scientist
Edsger W. Dijkstra (he used "P()" and "V()" instead of "acquire()" and
"release()").

A semaphore manages an internal counter which is decremented by each
"acquire()" call and incremented by each "release()" call.  The
counter can never go below zero; when "acquire()" finds that it is
zero, it blocks, waiting until some other thread calls "release()".

class threading.Semaphore([value])

   オプションの引数には、内部カウンタの初期値を指定します。デフォルト
   は "1" です。与えられた *value* が 0 より小さい場合、 "ValueError"
   が送出されます。

   acquire([blocking])

      セマフォを獲得します。

      When invoked without arguments: if the internal counter is
      larger than zero on entry, decrement it by one and return
      immediately.  If it is zero on entry, block, waiting until some
      other thread has called "release()" to make it larger than zero.
      This is done with proper interlocking so that if multiple
      "acquire()" calls are blocked, "release()" will wake exactly one
      of them up.  The implementation may pick one at random, so the
      order in which blocked threads are awakened should not be relied
      on.  There is no return value in this case.

      When invoked with *blocking* set to true, do the same thing as
      when called without arguments, and return true.

      *blocking* を false にして呼び出すとブロックしません。引数なしで
      呼び出した場合にブロックするような状況であった場合には直ちに
      false を返します。それ以外の場合には、引数なしで呼び出したときと
      同じ処理を行い true を返します。

   release()

      内部カウンタを 1 インクリメントして、セマフォを解放します。
      "release()" 処理に入ったときにカウンタがゼロであり、カウンタの値
      がゼロより大きくなるのを待っている別のスレッドがあった場合、その
      スレッドを起こします。


"Semaphore" の例
----------------

セマフォはしばしば、容量に限りのある資源、例えばデータベースサーバなど
を保護するために使われます。リソースが固定の状況では、常に有限セマフォ
を使わなければなりません。主スレッドは、作業スレッドを立ち上げる前にセ
マフォを初期化します:

   maxconnections = 5
   ...
   pool_sema = BoundedSemaphore(value=maxconnections)

作業スレッドは、ひとたび立ち上がると、サーバへ接続する必要が生じたとき
にセマフォの "acquire()" および "release()" メソッドを呼び出します:

   pool_sema.acquire()
   conn = connectdb()
   ... use connection ...
   conn.close()
   pool_sema.release()

有限セマフォを使うと、セマフォを獲得回数以上に解放してしまうというプロ
グラム上の間違いを見逃しにくくします。


Event オブジェクト
==================

イベントは、あるスレッドがイベントを発信し、他のスレッドはそれを待つと
いう、スレッド間で通信を行うための最も単純なメカニズムの一つです。

イベントオブジェクトは内部フラグを管理します。このフラグは "set()" メ
ソッドで値を true に、 "clear()" メソッドで値を false にリセットします
。 "wait()" メソッドはフラグが true になるまでブロックします。

class threading.Event

   The internal flag is initially false.

   is_set()
   isSet()

      内部フラグの値が true である場合にのみ true を返します。

      バージョン 2.6 で変更: Added "is_set()" spelling.

   set()

      内部フラグの値を true にセットします。フラグの値が true になるの
      を待っている全てのスレッドを起こします。一旦フラグが true になる
      と、スレッドが "wait()" を呼び出しても全くブロックしなくなります
      。

   clear()

      内部フラグの値を false にリセットします。以降は、 "set()" を呼び
      出して再び内部フラグの値を true にセットするまで、 "wait()" を呼
      び出したスレッドはブロックするようになります。

   wait([timeout])

      内部フラグの値が true になるまでブロックします。 "wait()" 処理に
      入った時点で内部フラグの値が true であれば、直ちに処理を戻します
      。そうでない場合、他のスレッドが "set()" を呼び出してフラグの値
      を true にセットするか、オプションのタイムアウトが発生するまでブ
      ロックします。

      *timeout* 引数を指定して、 "None" 以外の値にする場合、タイムアウ
      トを秒 (または端数秒) を表す浮動小数点数でなければなりません。

      This method returns the internal flag on exit, so it will always
      return "True" except if a timeout is given and the operation
      times out.

      バージョン 2.7 で変更: 以前は、このメソッドは常に "None" を返し
      ていました。


Timer オブジェクト
==================

このクラスは、一定時間経過後に実行される活動、すなわちタイマ活動を表現
します。 "Timer" は "Thread" のサブクラスであり、自作のスレッドを構築
した一例でもあります。

タイマは "start()" メソッドを呼び出すとスレッドとして作動し始めします
。 (活動を開始する前に) "cancel()" メソッドを呼び出すと、タイマを停止
できます。タイマが活動を実行するまでの待ち時間は、ユーザが指定した待ち
時間と必ずしも厳密には一致しません。

例えば:

   def hello():
       print "hello, world"

   t = Timer(30.0, hello)
   t.start()  # after 30 seconds, "hello, world" will be printed

class threading.Timer(interval, function, args=[], kwargs={})

   Create a timer that will run *function* with arguments *args* and
   keyword arguments *kwargs*, after *interval* seconds have passed.

   cancel()

      タイマをストップして、その動作の実行をキャンセルします。このメソ
      ッドはタイマがまだ活動待ち状態にある場合にのみ動作します。


"with" 文でのロック・条件変数・セマフォの使い方
===============================================

All of the objects provided by this module that have "acquire()" and
"release()" methods can be used as context managers for a "with"
statement.  The "acquire()" method will be called when the block is
entered, and "release()" will be called when the block is exited.

Currently, "Lock", "RLock", "Condition", "Semaphore", and
"BoundedSemaphore" objects may be used as "with" statement context
managers.  For example:

   import threading

   some_rlock = threading.RLock()

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


Importing in threaded code
==========================

While the import machinery is thread-safe, there are two key
restrictions on threaded imports due to inherent limitations in the
way that thread-safety is provided:

* Firstly, other than in the main module, an import should not have
  the side effect of spawning a new thread and then waiting for that
  thread in any way. Failing to abide by this restriction can lead to
  a deadlock if the spawned thread directly or indirectly attempts to
  import a module.

* Secondly, all import attempts must be completed before the
  interpreter starts shutting itself down. This can be most easily
  achieved by only performing imports from non-daemon threads created
  through the threading module. Daemon threads and threads created
  directly with the thread module will require some other form of
  synchronization to ensure they do not attempt imports after system
  shutdown has commenced. Failure to abide by this restriction will
  lead to intermittent exceptions and crashes during interpreter
  shutdown (as the late imports attempt to access machinery which is
  no longer in a valid state).
