KBEngine 内嵌 Python 3.7 的 _thread 低级线程 API 完全指南
KBEngine 内嵌 Python 3.7 的 _thread 低级线程 API 完全指南
本文以 KBEngine 仓库内嵌 Python 3.7.3 标准库文档 library/_thread.rst 为骨架,结合仓库内 Modules/_threadmodule.c 的 C 实现源码、Lib/threading.py 的高层封装以及 Lib/test/lock_tests.py 的官方测试用例,系统讲解
_thread模块的每个常量、函数与锁对象方法。读者读完后,将能够用_thread直接创建原生线程、用互斥锁协调共享数据访问,并理解 KBEngine 引擎内嵌 Python 解释器的线程基础设施是如何工作的。
KBEngine 是一个开源 MMOG 服务器引擎,其仓库 kbe/src/lib/python 目录下完整内嵌了一份 Python 3.7.3 源码(见 Include/patchlevel.h 中 PY_MAJOR_VERSION 3 / PY_MINOR_VERSION 7 / PY_MICRO_VERSION 3 的定义),引擎的 Python 脚本层(baseapp、cellapp、dbmgr 等进程内的实体逻辑)都运行在这份解释器之上。_thread 正是这份解释器中最底层的线程模块——threading 模块的所有高层对象(Thread、Lock、RLock、Event 等)都直接建立在 _thread 之上。
一、模块定位:Python 线程 API 的底层基石
_thread 模块为多线程编程提供最原始的底层原语。文档原文将它描述为:提供用于操作多个线程(也被称为"轻量级进程" light-weight processes 或"任务" tasks)的低级原语,多个控制线程共享它们全局的数据空间;为了同步,模块提供简单的锁(也被称为"互斥锁" mutexes 或"二元信号量" binary semaphores)。而 threading 模块则是在此之上构建的、更易用、更高级的线程 API。
该模块在 Python 3.7 中始终可用(versionchanged 3.7:此模块过去是可选的,现在总是可用)。在 CPython 源码层面,这一点体现在 Modules/_threadmodule.c 中,模块通过 PyModuleDef 结构注册为内建模块 "_thread"(PyModuleDef_HEAD_INIT, "_thread", ...),初始化函数为 PyInit__thread。
在 KBEngine 的 Python 3.7.3 解释器中,C 层线程原语(PyThread_start_new_thread、PyThread_allocate_lock 等)分别对应 POSIX 线程(pthread)与 Windows 线程两套实现,模块因此天然支持 Linux 服务器与 Windows 客户端两种运行环境。
从源码看 _thread 与 threading 的关系
打开 Lib/threading.py 可以清晰看到高层 API 如何依赖底层模块:
import _thread
_start_new_thread = _thread.start_new_thread
_allocate_lock = _thread.allocate_lock
...
Lock = _allocate_lock
- 第 5 行直接
import _thread; - 第 33-34 行把
_thread.start_new_thread与_thread.allocate_lock分别保存为_start_new_thread与_allocate_lock,作为所有线程启动与锁创建的基础; - 第 73 行
Lock = _allocate_lock——即threading.Lock本质上就是_thread的锁对象本身; - 第 1255 行
from _thread import stack_size——threading.stack_size直接转发到底层实现; - 第 1302 行
from _thread import _local as local——线程局部存储threading.local也来自_thread。
也就是说,理解 _thread 就等于理解了 threading 的底层实现原理。
二、模块级常量与函数
_thread 模块定义如下常量与函数(均可在 C 实现 Modules/_threadmodule.c 的 thread_methods 方法表中找到对应注册项)。
2.1 异常 _thread.error
线程相关的错误会抛出 error 异常。自 Python 3.3 起,它成为内建异常 RuntimeError 的别名(versionchanged 3.3)。在 Modules/_threadmodule.c 中可以看到:
ThreadError = PyExc_RuntimeError;
Py_INCREF(ThreadError);
PyDict_SetItemString(d, "error", ThreadError);
因此在实际代码中,except _thread.error 与 except RuntimeError 等价。常见的触发场景包括:在已持有锁的线程中重复加锁(死锁前兆)、线程栈大小设置不被平台支持等。
2.2 类型 _thread.LockType
LockType 是锁对象的类型。它对应的 C 类型为 Locktype,在 Modules/_threadmodule.c 通过 PyType_Ready(&Locktype) 完成初始化。可以用它做类型判断:
import _thread
lock = _thread.allocate_lock()
print(isinstance(lock, _thread.LockType)) # True
2.3 启动线程 start_new_thread(function, args[, kwargs])
启动一个新线程并返回其标识符(thread identifier)。新线程以参数列表 args(必须是元组)执行函数 function;可选参数 kwargs 指定关键字参数字典。
- 当函数正常返回时,线程静默退出;
- 当函数因未捕获异常而终止时,会打印堆栈跟踪(stack trace),随后线程退出,但其他线程继续运行——这点与主线程崩溃不同,不会波及整个进程。
在 C 实现 Modules/_threadmodule.c 中,该函数通过 PyArg_UnpackTuple(fargs, "start_new_thread", 2, 3, ...) 接收 2 到 3 个参数(function、args、可选 kwargs),然后调用平台线程创建函数启动原生线程。
import _thread
import time
def worker(name, delay):
time.sleep(delay)
print(f"[{name}] 线程运行完成,线程标识: {_thread.get_ident()}")
# args 必须是元组,kwargs 是字典
tid = _thread.start_new_thread(worker, ("t1",), {"delay": 1.0})
print("已启动线程,标识符:", tid)
# 注意:主线程结束后,其他线程可能被终止,因此通常需要等待
time.sleep(2)
2.4 中断主线程 interrupt_main()
在主线程中引发 KeyboardInterrupt 异常。子线程可以用它来打断主线程的阻塞操作。
import _thread
import time
def timeout_killer():
time.sleep(3)
print("超时,中断主线程...")
_thread.interrupt_main()
_thread.start_new_thread(timeout_killer, ())
try:
while True:
time.sleep(0.5)
except KeyboardInterrupt:
print("主线程被中断,执行清理逻辑")
注意文档中的 Caveat:线程与中断的交互比较特殊——KeyboardInterrupt 异常会被任意一个线程接收到;只有 signal 模块可用时(即主线程场景),中断才会总是投递给主线程。而 _thread.interrupt_main() 正是把中断定向投递给主线程的手段。
2.5 退出当前线程 _thread.exit()
引发 SystemExit 异常。当该异常未被捕获时,会导致线程静默退出。文档特别指出:调用 sys.exit() 或抛出 SystemExit 与调用 _thread.exit() 等价。
import _thread
def short_lived():
print("线程即将退出")
_thread.exit() # 等价于 sys.exit() / raise SystemExit
_thread.start_new_thread(short_lived, ())
2.6 创建锁 allocate_lock()
返回一个新的锁对象(初始状态为未锁定)。这是 _thread 中最核心的同步原语,对应 C 实现中的 thread_PyThread_allocate_lock,其核心作用保证"同一时刻只有一个线程能持有该锁",从而保护共享数据的互斥访问。
import _thread
a_lock = _thread.allocate_lock()
print("初始是否锁定:", a_lock.locked()) # False
2.7 获取当前线程标识 get_ident()
返回当前线程的"线程标识符"(非零整数)。该值本身没有直接含义,设计目的是作为"魔法饼干"(magic cookie)使用——例如用作字典键来索引线程专属数据。需要注意:当线程退出、新线程被创建时,线程标识符可能被回收复用,因此不要长期缓存标识符来指代某个具体线程。
import _thread
def show_ident():
print("当前线程 id:", _thread.get_ident())
_thread.start_new_thread(show_ident, ())
print("主线程 id:", _thread.get_ident())
2.8 线程栈大小 stack_size([size])
返回创建新线程时使用的线程栈大小:
- 可选参数
size指定随后创建的线程的栈大小,必须为 0(使用平台或配置的默认值)或至少 32768(32 KiB)的正整数; - 若不传
size,则按 0 处理(返回当前设置/默认值); - 若平台不支持修改线程栈大小,抛出
RuntimeError; - 若指定的栈大小非法,抛出
ValueError且栈大小保持不变。
32 KiB 是目前支持的最小栈大小,目的是保证解释器自身有足够的栈空间。部分平台对栈大小有额外限制,例如要求最小栈大于 32 KiB,或要求按系统内存页大小(memory page size)的整数倍分配——4 KiB 页很常见,在没有更具体信息时,建议使用 4096 的倍数作为栈大小。该函数的可用性(availability)限定为 Windows 与支持 POSIX 线程的系统。
import _thread
print("当前栈大小:", _thread.stack_size()) # 返回默认/已配置大小
old = _thread.stack_size(64 * 1024) # 设置后续线程栈为 64 KiB
print("设置前的大小:", old)
_thread.stack_size(0) # 恢复为平台默认
需要说明的是:KBEngine 服务端进程中大量脚本线程由引擎统一调度,通常建议保持默认栈大小(传 0),除非你明确知道脚本调用栈很深、需要加大栈空间。
2.9 超时上限 _thread.TIMEOUT_MAX
Lock.acquire 的 timeout 参数允许的最大值。指定超过此值的超时会抛出 OverflowError。该常量自 Python 3.2 起提供(versionadded 3.2)。
在 C 实现 Modules/_threadmodule.c 中可以看到它的计算方式:
timeout_max = (_PyTime_t)PY_TIMEOUT_MAX * 1e-6;
time_max = _PyTime_AsSecondsDouble(_PyTime_MAX);
timeout_max = Py_MIN(timeout_max, time_max);
/* Round towards minus infinity */
timeout_max = floor(timeout_max);
v = PyFloat_FromDouble(timeout_max);
PyModule_AddObject(m, "TIMEOUT_MAX", v);
即 TIMEOUT_MAX 是 PY_TIMEOUT_MAX(内部时间微秒上限)换算成秒后再与 _PyTime_MAX 取最小值并向下取整得到的浮点数。
三、锁对象(LockType)的完整方法
锁对象支持以下方法。
3.1 lock.acquire(waitflag=1, timeout=-1)
获取锁,这是锁对象最核心的方法。分三种模式:
- 无条件阻塞获取(不传任何可选参数):如果必要则等待直到锁被其他线程释放。同一时刻只有一个线程能获取锁——这正是锁存在的意义。
- 非阻塞尝试获取(传入整型
waitflag=0):只在能立即获得锁时才获取,不等待。 - 带超时的获取(传入正的浮点
timeout):timeout以秒为单位,指定返回前的最长等待时间;负的timeout表示无限期等待。
限制:如果 waitflag 为 0(非阻塞),则不能指定 timeout。返回值:成功获取返回 True,否则返回 False。
versionchanged 3.2:timeout参数是新增的;versionchanged 3.2:在 POSIX 上锁的获取现在可以被信号中断。
在 Modules/_threadmodule.c 可以看到超时参数在 C 层被转换为微秒级别(if (microseconds >= PY_TIMEOUT_MAX)),超出上限会走异常路径。
import _thread
import time
lock = _thread.allocate_lock()
# 模式一:阻塞获取
lock.acquire()
print("已持有锁")
# 模式二:非阻塞尝试
if lock.acquire(0):
print("立即获取成功") # 不可能执行到这里
else:
print("锁已被占用,获取失败") # 会执行到这里
lock.release()
# 模式三:带超时获取
if lock.acquire(timeout=0.5):
print("1 秒内获得锁")
lock.release()
3.2 lock.release()
释放锁。锁必须已经被获取过,但不一定要由同一个线程释放——这是 _thread 锁与普通"可重入锁"(RLock)的重要区别:底层锁并不记录持有者线程。也就是说线程 A 加的锁可以由线程 B 释放。
import _thread
lock = _thread.allocate_lock()
lock.acquire()
lock.release() # 谁持有、谁释放均可
print("锁已释放:", lock.locked()) # False
3.3 lock.locked()
返回锁的状态:若已被某个线程获取则返回 True,否则返回 False。常用于非阻塞轮询前的状态探测。
3.4 锁的 with 语句支持
除了上述方法,锁对象还可以直接用于 with 语句。文档给出的标准示例:
import _thread
a_lock = _thread.allocate_lock()
with a_lock:
print("a_lock is locked while this executes")
等价于:
a_lock.acquire()
try:
print("a_lock is locked while this executes")
finally:
a_lock.release()
注意:with 语句在退出时必定释放锁,即使块内抛出异常也不会造成死锁,因此这是推荐写法。官方测试 Lib/test/lock_tests.py 的 test_with 用例专门验证了 with lock: 在正常退出与抛出 TypeError 两种情况下锁都会被正确释放。
3.5 锁对象在 C 层的形态
从 Modules/_threadmodule.c 的 lock_doc 文档字符串可以看到 CPython 对锁对象的权威描述:
"A lock object is a synchronization primitive. ... acquire() -- lock the lock, possibly blocking until it can be obtained; release() -- unlock of the lock; locked() -- test whether the lock is currently locked. A lock is not owned by the thread that locked it; another thread may unlock it. A thread attempting to lock a lock that it has already locked will block until another thread unlocks it. Deadlocks may ensue."
这段描述点出了 _thread 锁的两个关键特性:锁不被持有者线程所有(其他线程可解锁),以及同一线程对自己已持有的锁再次加锁会阻塞直到解锁——这正是死锁(deadlock)的经典成因,也正是 threading.RLock(可重入锁)存在的理由。
四、官方测试对锁行为的验证
KBEngine 内嵌 Python 的标准库测试 Lib/test/lock_tests.py 对上述行为做了系统性验证,可作为行为契约的权威参照:
test_acquire_release(第 110 行):加锁后释放,验证基本流程;test_try_acquire/test_try_acquire_contended(第 116-129 行):acquire(False)非阻塞获取——空闲锁立即获取成功(返回True),被占用的锁立即失败(返回False);test_acquire_contended(第 131-145 行):5 个线程同时争抢一个锁,只有持有者释放后其他线程才能依次获取;test_with(第 147-161 行):with语句正常与异常路径下锁均被正确释放;test_timeout(第 182-197 行):不能为非阻塞获取指定 timeout;非法负超时抛出ValueError;超过TIMEOUT_MAX + 1的超时抛出OverflowError;timeout=TIMEOUT_MAX本身合法;带正超时的获取在锁空闲时立即成功;test_state_after_timeout(第 258-263 行):超时返回后锁保持未获取状态(assertFalse(lock.acquire(timeout=0.01)))。
这些用例同时覆盖了纯 _thread 锁(LockTests)与 threading.Lock,再次印证二者实为同一对象。
五、重要注意事项(Caveats)
原文档给出的五大注意事项是编写多线程代码时必须牢记的边界行为:
- 线程与中断的奇怪交互:
KeyboardInterrupt异常会被任意一个线程接收到;当signal模块可用时(主线程场景),中断总是投递给主线程。 sys.exit/SystemExit与_thread.exit等价:三者都会导致线程静默退出。- 无法中断锁的
acquire:KeyboardInterrupt只会发生在锁被获取之后,等待获取期间不会被中断——因此长等待可能表现为"卡住",务必善用timeout参数。 - 主线程退出时其他线程的生死由系统决定:在大多数系统上,其他线程会被直接杀掉,不会执行
try...finally子句,也不会执行对象析构函数。 - 主线程退出时不做常规清理:除了会执行
try...finally子句外,标准 I/O 文件不会被刷新(flush)。
其中第 3、4 条对服务器脚本有直接警示:不要让主线程轻易返回,也不要依赖子线程的 finally 或析构逻辑做关键清理。KBEngine 各服务进程(baseapp、cellapp 等)的主循环长期运行、线程生命周期由引擎组件管理,因此脚本侧通常不应自行创建裸线程——如需并发逻辑,建议优先使用引擎提供的回调与定时器机制,或在确有需要时使用 threading 高层模块并严格控制线程生命周期。
六、实战总结
_thread 是理解 Python 线程模型的"最小知识集":
| 功能 | API | 要点 |
|---|---|---|
| 启动线程 | start_new_thread(fn, args[, kwargs]) |
args 必须是元组;未捕获异常仅打印栈后线程退出 |
| 创建锁 | allocate_lock() |
初始未锁定;类型为 LockType |
| 获取锁 | acquire(waitflag=1, timeout=-1) |
支持阻塞 / 非阻塞(0)/ 带超时三种模式 |
| 释放锁 | release() |
不要求由持有者线程释放 |
| 查询锁 | locked() |
返回布尔状态 |
| 线程标识 | get_ident() |
非零整数,可作字典键,会被回收复用 |
| 栈大小 | stack_size([size]) |
最小 32 KiB,建议取 4096 的倍数 |
| 退出线程 | exit() |
等价于 sys.exit() / raise SystemExit |
| 中断主线程 | interrupt_main() |
向主线程投递 KeyboardInterrupt |
| 超时上限 | TIMEOUT_MAX |
超过会抛 OverflowError |
在实际工程中,_thread 的价值在于它足够简单、足够快,且是 threading 的全部底层来源。KBEngine 内嵌的这份 Python 3.7.3 标准库(源码位于 kbe/src/lib/python,模块文档位于 Doc/library/_thread.rst,C 实现在 Modules/_threadmodule.c)随时可供深入阅读,读者可以按图索骥,从文档到实现再到测试用例,完整掌握这一底层线程 API 的每一个细节。