17.1. `threading` — 基于线程的并行 ¶

源代码： Lib/threading.py

此模块构造更高级线程接口，基于更低级 _thread 模块。另请参阅 queue 模块。

The dummy_threading 模块的提供是为当 threading 无法使用由于 _thread 缺失。

注意

虽然它们未在以下列出，但 camelCase 名称用于由此模块仍支持的 Python 2.x 系列中的此模块的某些方法和函数。

此模块定义了下列函数：

threading. active_count ( ) ¶

threading. current_thread ( ) ¶

threading. get_ident ( ) ¶

threading. enumerate ( ) ¶

threading. main_thread ( ) ¶

threading. settrace ( func ) ¶: 为所有线程设置跟踪函数开始于 threading 模块。 func 将被传递给 sys.settrace() 为各线程，先于其 run() 方法被调用。

threading. setprofile ( func ) ¶: 为所有线程设置 profile 函数开始于 threading 模块。 func 将被传递给 sys.setprofile() 为各线程，先于其 run() 方法被调用。

threading. stack_size ( [ size ] ) ¶

此模块还定义了下列常量：

threading. TIMEOUT_MAX ¶

此模块定义了许多类，以下章节会详细描述。

此模块的设计基于 Java 的松散线程化模型。然而，Java 使锁和条件变量成为每个对象的基本行为，它们在 Python 中是独立对象。Python 的 Thread 类是支持 Java 线程类行为的子集；目前，没有优先级，没有线程组，线程无法被销毁、停止、挂起、恢复或中断。Java 线程类的静态方法，在实现时被映射到了模块级函数。

下文描述的所有方法都以原子方式执行。

17.1.1. 线程本地数据 ¶

线程局部数据是值为特定线程的数据。要管理线程局部数据，仅仅创建实例化的 local (或子类) 并在其中存储属性：

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

实例的值异于单独线程。

class threading. local ¶

17.1.2. 线程对象 ¶

The Thread 类表示在单独控制线程中运行的活动。有 2 种方式指定活动：通过将可调用对象传递给构造函数，或通过覆盖 run() 方法在子类中。不应覆盖子类中的其它方法 (除构造函数外)。换句话说， only 覆写 __init__() and run() 方法对于此类。

线程对象一旦被创建，它的活动就必须被启动通过调用线程的 start() 方法。这援引 run() 方法在单独控制线程中。

一旦线程活动开始，就认为线程 "存活"。它将停止存活当其 run() 方法被终止 – 正常或通过引发未处理异常。 is_alive() 方法测试线程是否存活。

其它线程可以调用线程的 join() 方法。这阻塞调用线程，直到线程的 join() 方法被调用才终止。

线程有名称。名称会被传递给构造函数，且读取和改变是透过 name 属性。

可以将线程标志为 "守护线程"。此标志的意义，整个 Python 程序退出当只剩守护线程时。初始值继承自创建线程。标志可以设置透过 daemon 特性或 daemon 构造函数自变量。

注意

守护线程在关闭时会突然停止。它们的资源 (譬如：打开文件、数据库事务、等) 不可能正确释放。若想要线程优雅停止，使它们成为非守护并使用合适的发信号机制，譬如 Event .

存在 "主线程" 对象；这相当于 Python 程序中的初始控制线程。它不是守护线程。

有可能创建 "虚设线程对象"。这些是 "外来线程" 的对应线程对象，是在 threading 模块外开始的控制线程 (譬如：直接从 C 代码)。虚设线程对象拥有有限功能；认为它们始终存活和守护，且不可以 join() 。它们从不被删除，由于不可能检测外来线程的终止。

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

start ( ) ¶

run ( ) ¶

join ( timeout=None ) ¶

名称 ¶

getName ( ) ¶
setName ( ) ¶

ident ¶

is_alive ( ) ¶

daemon ¶

isDaemon ( ) ¶
setDaemon ( ) ¶

CPython 实现细节： 在 CPython，由于全局解释器锁，一次仅一线程可以执行 Python 代码 (即使某些面向性能的库可以克服此局限性)。若想让应用程序更好地利用多核机器的计算资源，建议使用 multiprocessing or concurrent.futures.ProcessPoolExecutor 。不管怎样，threading 仍是合适模型若想要同时运行多个 I/O 绑定任务。

17.1.3. 锁对象 ¶

原语锁是锁定时不属于特定线程的同步原语。在 Python 中，它目前是可用的最低级同步原语，直接实现通过 _thread 扩展模块。

原语锁处于锁定或解锁 2 种状态之一。它是在解锁状态下创建的。它拥有 2 个基本方法， acquire() and release() 。当在解锁状态时， acquire() 将状态改为锁定并立即返回。当在锁定状态时， acquire() 阻塞直到调用 release() 在另一线程中将其改为解锁，然后 acquire() 调用将它重置为锁定并返回。 release() 方法只应在锁定状态下调用；它将状态改为解锁并立即返回。若试图释放未锁定的锁， RuntimeError 会被引发。

锁还支持上下文管理协议 .

当多个阻塞线程在 acquire() 等待状态变为解锁，仅一线程继续进行当 release() 调用将状态重置为解锁；哪个等待线程继续执行未定义，且可能因实现而异。

所有方法以原子方式执行。

class threading. 锁 ¶

acquire ( blocking=True , timeout=-1 ) ¶

release ( ) ¶

17.1.4. RLock 对象 ¶

可重入锁是可以被同一线程多次获得的同步原语。在内部，它使用 owning thread (拥有线程) 和 recursion level (递归级别) 概念，除原语锁使用的锁定/解锁状态外。在锁定状态下，某个线程拥有锁；在解锁状态下，没有线程拥有它。

为锁定锁，线程调用它的 acquire() 方法；这返回，一旦线程拥有锁。为解锁锁，线程调用它的 release() 方法。 acquire() / release() 调用对可以嵌套；才最后 release() ( release() 最外侧对) 将锁重置为解锁，并允许阻塞另一线程当 acquire() 以继续进行。

可重入锁还支持上下文管理协议 .

class threading. RLock ¶

此类实现可重入锁对象。可重入锁必须由获得它的线程释放。一旦线程获得可重入锁，同一线程可以再次获得它不阻塞；线程必须释放它一次，每次获得它时。

注意， RLock 实际是工厂函数，返回由平台支持的具体 RLock 类的最高效版本实例。

acquire ( blocking=True , timeout=-1 ) ¶

release ( ) ¶

17.1.5. 条件对象 ¶

条件变量始终关联某种锁；这可以传入 (或默认创建) 一个。传入一个很有用，当几个条件变量必须共享同一锁时。锁属于条件对象：不必单独追踪它。

条件变量遵从上下文管理协议：使用 with 语句可在封闭块持续时间内获得关联锁。 acquire() and release() 方法还调用关联锁的相应方法。

必须在持有关联锁时，调用其它方法。 wait() 方法释放锁，然后阻塞，直到另一个线程唤醒它通过调用 notify() or notify_all() 。一旦被唤醒， wait() 重新获得锁并返回。此外，还可以指定超时。

The notify() 方法唤醒在等待条件变量的某一线程，若有在等待。 notify_all() 方法唤醒在等待条件变量的所有线程。

注意： notify() and notify_all() 方法不会释放锁；这意味着线程 (或被唤醒线程) 将不会返回从其 wait() 调用立即，但仅当线程调用 notify() or notify_all() 最后会放弃锁的所有权。

使用条件变量的典型编程样式，是使用锁同步访问某些共享状态；对特定状态变化感兴趣的线程会调用 wait() 重复直到它们看到期望状态，而修改状态的线程会调用 notify() or notify_all() 当它们改变状态时，以这种方式，它可能是某个等待者所期望的状态。例如，以下代码是具有不受限制缓冲容量的一般生产者/消费者情况：

# Consume one item
with cv:
    while not an_item_is_available():
        cv.wait()
    get_an_available_item()
# Produce one item
with cv:
    make_an_item_available()
    cv.notify()

The while 循环校验应用程序条件是必要的，因为 wait() 可以在任意长时间后返回，且条件提示 notify() 调用可以不再保持 True。这是多线程编程所固有的。 wait_for() 方法可以用于自动条件校验，并简化计算超时：

# Consume an item
with cv:
    cv.wait_for(an_item_is_available)
    get_an_available_item()

要选取介于 notify() and notify_all() ，考虑一种状态的改变是否只对一个或多个正等待线程感兴趣。如：在典型生产者/消费者情况下，向缓冲添加一项只需唤醒一个消费者线程。

class threading. 条件 ( lock=None ) ¶

此类实现条件变量对象。条件变量允许一个或多个线程去等待，直到由另一线程通知它们。

若 lock 自变量有给定且不是 None ，它必须是 Lock or RLock 对象，且它被用作底层锁。否则，新的 RLock 对象被创建并用作底层锁。

3.3 版改变：从工厂函数变为类。

acquire ( *args ) ¶

release ( ) ¶

wait ( timeout=None ) ¶

等待直到被通知 (或直到发生超时)。若调用此方法时调用线程尚未获得锁， RuntimeError 被引发。

此方法释放底层锁，然后阻塞直到被唤醒由 notify() or notify_all() 调用对于在另一线程中的的相同条件变量，或直到发生可选超时为止。一旦被唤醒或超时，它重新获得锁并返回。

当 timeout 自变量存在且非 None ，它应该是以秒 (或其分数) 为单位指定操作超时的浮点数。

当底层锁为 RLock ，它不会被释放使用 release() 方法，由于这可能实际并未被解锁，当多次递归获得锁时。相反，内部接口的 RLock 类的使用，这真的会解锁，甚至在已递归获得几次时。然后使用另一内部接口恢复递归级别，当重新获得锁时。

返回值为 True 除非给定 timeout 过期，在这种情况下为 False .

3.2 版改变：以前，方法总是返回 None .

wait_for ( predicate , timeout=None ) ¶

等待直到条件被评估为 True 止。 predicate 应该是其结果将被解释成布尔值的可调用。 timeout 可以提供最大给定等待时间。

此实用方法可以调用 wait() 重复直到 predicate (谓词) 被满足，或直到发生 timeout (超时)。返回值是谓词的最后返回值，并将评估为 False 若方法超时。

忽略超时特征，调用此方法大致相当于编写：

while not predicate():
    cv.wait()

因此，相同规则也适用于 wait() ：调用时必须持有锁，而返回时重新获得锁。predicate (谓词) 在持有锁时评估。

3.2 版新增。

notify ( n=1 ) ¶

默认情况下，只唤醒等待此条件的线程 (若有的话)。若调用线程未获得锁当调用此方法时， RuntimeError 被引发。

此方法最多唤醒 n 个等待条件变量的线程；无操作若没有线程在等待。

当前实现准确唤醒 n 线程，若至少 n 线程在等待。不管怎样，依赖此行为不安全。未来，优化实现可能偶尔唤醒超过 n 线程。

注意：被唤醒线程并不实际返回从其 wait() 调用直到它可以重新获得锁。由于 notify() 不释放锁，其调用者应释放锁。

notify_all ( ) ¶: 唤醒在等待此条件的所有线程。此方法的举动像 notify() ，但唤醒所有在等待线程，而不是一个。若调用线程未获得锁当调用此方法时， RuntimeError 被引发。

17.1.6. 信号量对象 ¶

这是计算机科学史中最古老的同步原语之一，由早期荷兰计算机科学家 Edsger W. Dijkstra 发明（他使用名称 P() and V() 而不是 acquire() and release() ).

信号量管理的内部计数器的递减是通过每 acquire() 调用和递增是通过每 release() 调用。计数器可以从不低于 0；当 acquire() 发现它为 0，阻塞，等待直到某些其它线程调用 release() .

信号量还支持上下文管理协议 .

class threading. 信号量 ( value=1 ) ¶

This class implements semaphore objects. A semaphore manages a counter representing the number of release() 调用减数 acquire() 调用，加初始值。 acquire() 方法阻塞若有必要直到它可以在不用使计数器为负的情况下返回。若不给定， value 默认为 1。

可选自变量给出初始 value 对于内部计数器；默认为 1 。若 value 给定小于 0， ValueError 被引发。

3.3 版改变：从工厂函数变为类。

acquire ( blocking=True , timeout=None ) ¶

获得信号量。

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. Returns true (or blocks indefinitely).

当被援引采用 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.

当援引采用 timeout 除了 None ，它将阻塞最多 timeout seconds. If acquire does not complete successfully in that interval, return false. Return true otherwise.

3.2 版改变： The timeout 参数是新增的。

release ( ) ¶: Release a semaphore, incrementing the internal counter by one. When it was zero on entry and another thread is waiting for it to become larger than zero again, wake up that thread.

class threading. BoundedSemaphore ( value=1 ) ¶

实现有界信号量对象的类。有界信号量会校验，以确保其当前值不超过其初始值。若履行， ValueError 被引发。在大多数情况下，信号量用于守卫容量有限的资源。若释放信号量太多次，有 Bug 迹象。若不给定， value 默认为 1。

3.3 版改变：从工厂函数变为类。

17.1.6.1. `Semaphore` 范例 ¶

信号量经常用于守卫容量有限的资源 (例如：数据库服务器)。在资源大小固定的任何情况下，都应使用有界信号量。在卵生任何工作者线程前，主线程会初始化信号量：

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

一旦卵生，工作者线程会调用信号量的获得和释放方法，当它们需要连接到服务器时：

with pool_sema:
    conn = connectdb()
    try:
        # ... use connection ...
    finally:
        conn.close()

使用有界信号量可以减少编程出错的机会，但会导致要多要释放的信号量，而不是获得检测。

17.1.7. 事件对象 ¶

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

事件对象管理可以设为 True 的内部标志采用 set() 方法和重置为 False 采用 clear() 方法。 wait() 方法阻塞直到标志为 True。

class threading. 事件 ¶

17.1.8. 计时器对象 ¶

此类表示仅在经过一定数量时间后才应运行的动作 — 计时器。 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=None , kwargs=None ) ¶

创建计时器将运行 function 采用自变量 args 和关键词自变量 kwargs ，后于 interval 秒过去。若 args is None (默认) 那么将使用空列表。若 kwargs is None (默认) 那么将使用空字典。

3.3 版改变：从工厂函数变为类。

cancel ( ) ¶: 停止计时器，并取消计时器动作的执行。这才工作，若计时器仍处于等待阶段。

17.1.9. 屏障对象 ¶

3.2 版新增。

此类提供简单同步原语，供需要相互等待的固定数量线程使用。每个线程会试着穿过屏障通过调用 wait() method and will block until all of the threads have made the call. At this points, the threads are released simultaneously.

可以重用屏障任意多次，对于相同数量的线程而言。

例如，这里是客户端和服务器线程的简单同步方式：

b = Barrier(2, timeout=5)
def server():
    start_server()
    b.wait()
    while True:
        connection = accept_connection()
        process_server_connection(connection)
def client():
    b.wait()
    while True:
        connection = make_connection()
        process_client_connection(connection)

class threading. 屏障 ( parties , action=None , timeout=None ) ¶

创建屏障对象为 parties 数量的线程。 action ，当提供时，是释放线程时由它们中某一线程调用的可调用。 timeout 是默认超时值，若指定 None 为 wait() 方法。

wait ( timeout=None ) ¶

通过屏障。当屏障的所有线程都有调用此函数时，将同时释放它们。若 timeout 有提供，首选使用它，相比提供给类构造函数的任何。

返回值是整数在范围 0 到 parties – 1，每个线程都不同。这可以用于选择线程做一些特殊内务，如：

i = barrier.wait()
if i == 0:
    # Only one thread needs to print this
    print("passed the barrier")

若 action 有提供给构造函数，某一线程会先于释放调用它。若此调用引发错误，会把屏障置于中断状态。

若调用超时，会把屏障置于中断状态。

此方法可能引发 BrokenBarrierError 异常，若屏障被中断 (或重置) 当线程在等待时。

reset ( ) ¶

返回空状态默认屏障。在等待它的任何线程将收到 BrokenBarrierError 异常。

Note that using this function may can require some external synchronization if there are other threads whose state is unknown. If a barrier is broken it may be better to just leave it and create a new one.

abort ( ) ¶

把屏障置于中断状态。这会导致任何活动或未来调用 wait() 失败采用 BrokenBarrierError . Use this for example if one of the needs to abort, to avoid deadlocking the application.

更可取的是只需创建屏障采用合理 timeout 值来自动守卫某一线程的出错。

parties ¶: 要求通过屏障的线程数。

n_waiting ¶: 目前在屏障中等待的线程数。

broken ¶: 布尔为 True 若屏障处于中断状态。

exception threading. BrokenBarrierError ¶: 此异常是子类化的 RuntimeError ，被引发当 Barrier 对象被重置或中断。

17.1.10. 使用锁、条件和信号量在 `with` 语句 ¶

由此模块提供的所有对象拥有 acquire() and release() 方法可以用作上下文管理器对于 with 语句。 acquire() 方法将被调用当进入块时，和 release() 将被调用当退出块时。因此，以下片段：

with some_lock:
    # do something...

相当于：

some_lock.acquire()
try:
    # do something...
finally:
    some_lock.release()

目前， Lock , RLock , Condition , Semaphore ，和 BoundedSemaphore 对象可以用作 with 语句上下文管理器。

17.1. threading — 基于线程的并行 ¶

17.1.1. 线程本地数据 ¶

17.1.2. 线程对象 ¶

17.1.3. 锁对象 ¶

17.1.4. RLock 对象 ¶

17.1.5. 条件对象 ¶

17.1.6. 信号量对象 ¶

17.1.6.1. Semaphore 范例 ¶

17.1.7. 事件对象 ¶

17.1.8. 计时器对象 ¶

17.1.9. 屏障对象 ¶

17.1.10. 使用锁、条件和信号量在 with 语句 ¶

内容表

上一话题

下一话题

本页

17.1. `threading` — 基于线程的并行 ¶

17.1.6.1. `Semaphore` 范例 ¶

17.1.10. 使用锁、条件和信号量在 `with` 语句 ¶