16.2. "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 条件对象.

threading.current_thread()
threading.currentThread()

   返回当前对应调用者的控制线程的 "Thread" 对象。如果调用者的控制线程
   不是利用 "threading" 创建，会返回一个功能受限的虚拟线程对象。

   在 2.6 版更改: Added "current_thread()" spelling.

threading.enumerate()

   以列表形式返回当前所有存活的 "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 事件对象.

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 锁对象.

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 递归锁对象.

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 信号量对象.

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 线程对象.

class threading.Timer

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

   See 定时器对象.

threading.settrace(func)

   为所有 "threading" 模块开始的线程设置追踪函数。在每个线程的 "run()"
   方法被调用前，*func* 会被传递给 "sys.settrace()" 。

   2.3 新版功能.

threading.setprofile(func)

   为所有 "threading" 模块开始的线程设置性能测试函数。在每个线程的
   "run()" 方法被调用前，*func* 会被传递给 "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 类的一个子集；目前还没有优先级，没有线
程组，线程还不能被销毁、停止、暂停、恢复或中断。 Java 的 Thread 类的静
态方法在实现时会映射为模块级函数。

下列描述的方法都是自动执行的。


16.2.1. 线程对象
================

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.

注解: 守护线程在程序关闭时会突然关闭。他们的资源（例如已经打开的文档
  ，数据 库事务等等）可能没有被正确释放。如果你想你的线程正常停止，设
  置他们成 为非守护模式并且使用合适的信号机制，例如： "Event"。

有个 “主线程” 对象；这对应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* 是线程名称。默认情况下，由 “Thread-*N*” 格式构成一个唯一的名
   称，其中 *N* 是小的十进制数。

   *args* 是用于调用目标函数的参数元组。默认是 "()"。

   *kwargs* 是用于调用目标函数的关键字参数字典。默认是 "{}"。

   如果子类型重载了构造函数，它一定要确保在做任何事前，先发起调用基类
   构造器("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.

      如果同一个线程对象中调用这个方法的次数大于一次，会抛出
      "RuntimeError" 。

   run()

      代表线程活动的方法。

      You may override this method in a subclass.  The standard
      "run()" method invokes the callable object passed to the
      object’s constructor as the *target* argument, if any, with
      sequential and keyword arguments taken from the *args* and
      *kwargs* arguments, respectively.

   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

      只用于识别的字符串。它没有语义。多个线程可以赋予相同的名称。 初
      始名称由构造函数设置。

      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".


16.2.2. 锁对象
==============

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.

   没有返回值。

   locked()
   Return true if the lock is acquired.


16.2.3. 递归锁对象
==================

重入锁是一个可以被同一个线程多次获取的同步基元组件。在内部，它在基元锁
的锁定/非锁定状态上附加了 “所属线程” 和 “递归等级” 的概念。在锁定状态
下，某些线程拥有锁 ； 在非锁定状态下， 没有线程拥有它。

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])

   可以阻塞或非阻塞地获得锁。

   当无参数调用时： 如果这个线程已经拥有锁，递归级别增加一，并立即返回
   。否则，如果其他线程拥有该锁，则阻塞至该锁解锁。一旦锁被解锁(不属于
   任何线程)，则抢夺所有权，设置递归等级为一，并返回。如果多个线程被阻
   塞，等待锁被解锁，一次只有一个线程能抢到锁的所有权。在这种情况下，
   没有返回值。

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

   When invoked with the *blocking* argument set to false, do not
   block.  If a call without an argument would block, return false
   immediately; otherwise, do the same thing as when called without
   arguments, and return true.

RLock.release()

   释放锁，自减递归等级。如果减到零，则将锁重置为非锁定状态(不被任何线
   程拥有)，并且，如果其他线程正被阻塞着等待锁被解锁，则仅允许其中一个
   线程继续。如果自减后，递归等级仍然不是零，则锁保持锁定，仍由调用线
   程拥有。

   只有当前线程拥有锁才能调用这个方法。如果锁被释放后调用这个方法，会
   引起 "RuntimeError" 异常。

   没有返回值。


16.2.4. 条件对象
================

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])

   如果给出了非 "None" 的 *lock* 参数，则它必须为 "Lock" 或者 "RLock"
   对象，并且它将被用作底层锁。否则，将会创建新的 "RLock" 对象，并将其
   用作底层锁。

   acquire(*args)

      请求底层锁。此方法调用底层锁的相应方法，返回值是底层锁相应方法的
      返回值。

   release()

      释放底层锁。此方法调用底层锁的相应方法。没有返回值。

   wait([timeout])

      等待直到被通知或发生超时。如果线程在调用此方法时没有获得锁，将会
      引发 "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()" 方法释放锁，因为
      当它被递归多次获取时，实际上可能无法解锁。相反，使用了 "RLock"
      类的内部接口，即使多次递归获取它也能解锁它。 然后，在重新获取锁
      时，使用另一个内部接口来恢复递归级别。

   notify(n=1)

      默认唤醒一个等待这个条件的线程。如果调用线程在没有获得锁的情况下
      调用这个方法，会引发 "RuntimeError" 异常。

      这个方法唤醒最多 *n* 个正在等待这个条件变量的线程；如果没有线程
      在等待，这是一个空操作。

      当前实现中，如果至少有 *n* 个线程正在等待，准确唤醒 *n* 个线程。
      但是依赖这个行为并不安全。未来，优化的实现有时会唤醒超过 *n* 个
      线程。

      注意：被唤醒的线程实际上不会返回它调用的 "wait()" ，直到它可以重
      新获得锁。因为 "notify()" 不会释放锁，只有它的调用者应该这样做。

   notify_all()
   notifyAll()

      唤醒所有正在等待这个条件的线程。这个方法行为与 "notify()" 相似，
      但并不只唤醒单一线程，而是唤醒所有等待线程。如果调用线程在调用这
      个方法时没有获得锁，会引发 "RuntimeError" 异常。

      在 2.6 版更改: Added "notify_all()" spelling.


16.2.5. 信号量对象
==================

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])

   可选参数 *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.

      When invoked with *blocking* set to false, do not block.  If a
      call without an argument would block, return false immediately;
      otherwise, do the same thing as when called without arguments,
      and return true.

   release()

      释放一个信号量，将内部计数器的值增加1。当计数器原先的值为0且有其
      它线程正在等待它再次大于0时，唤醒正在等待的线程。


16.2.5.1. "Semaphore" 例子
--------------------------

信号量通常用于保护数量有限的资源，例如数据库服务器。在资源数量固定的任
何情况下，都应该使用有界信号量。在生成任何工作线程前，应该在主线程中初
始化信号量。

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

工作线程生成后，当需要连接服务器时，这些线程将调用信号量的 acquire 和
release 方法：

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

使用有界信号量能减少这种编程错误：信号量的释放次数多于其请求次数。


16.2.6. 事件对象
================

这是线程之间通信的最简单机制之一：一个线程发出事件信号，而其他线程等待
该信号。

一个事件对象管理一个内部标志，调用 "set()" 方法可将其设置为true，调用
"clear()" 方法可将其设置为false，调用 "wait()" 方法将进入阻塞直到标志
为true。

class threading.Event

   The internal flag is initially false.

   is_set()
   isSet()

      Return true if and only if the internal flag is true.

      在 2.6 版更改: Added "is_set()" spelling.

   set()

      将内部标志设置为true。所有正在等待这个事件的线程将被唤醒。当标志
      为true时，调用 "wait()" 方法的线程不会被被阻塞。

   clear()

      将内部标志设置为false。之后调用 "wait()" 方法的线程将会被阻塞，
      直到调用 "set()" 方法将内部标志再次设置为true。

   wait([timeout])

      阻塞线程直到内部变量为true。如果调用时内部标志为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"。


16.2.7. 定时器对象
==================

此类表示一个操作应该在等待一定的时间之后运行 — 相当于一个定时器。
"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()

      停止定时器并取消执行计时器将要执行的操作。仅当计时器仍处于等待状
      态时有效。


16.2.8. Using locks, conditions, and semaphores in the "with" statement
=======================================================================

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"


16.2.9. 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).
