PyO3 中的#[pyclass]线程安全Send/Sync 约束、unsendable 退出机制与锁/原子变量实战指南【免费下载链接】pyo3Rust bindings for the Python interpreter项目地址: https://gitcode.com/gh_mirrors/py/pyo3Python 解释器允许任意 Python 线程自由地持有、访问和销毁同一个对象这决定了 PyO3 中一切#[pyclass]类型都必须满足 Rust 的Send与Sync约束。本文以 PyO3 指南的 thread-safety 章节 为主线完整讲解默认的内部可变性interior mutability模式如何自动保证线程安全、何时该用#[pyclass(unsendable)]退出该机制以及三种让自定义类彻底线程安全的实战方案——原子数据结构、互斥锁含与 GIL 相关的死锁规避与手动包装非线程安全数据。读完后你将能写出在任意多线程 Python 应用中行为正确、不会因Already borrowed运行时错误而崩溃的 PyO3 扩展类。为什么#[pyclass]必须Send且SyncPython 对象在线程之间的共享是完全自由的这意味着两件 Rust 编译器无法替你兜底的事情随时可能发生创建与销毁可能发生在不同线程你无法控制究竟是哪一个线程最终 drop 掉#[pyclass]对象因此该类型必须实现Send多个线程可能同时读取数据多个 Python 线程可以同时访问同一个#[pyclass]对象内部的数据因此该类型必须实现Sync。这两条约束在 PyO3 指南的 Python classes 总章 中被列为#[pyclass]的三大约束之一另外两条是不得有生命周期参数与不得有泛型参数其背后的原因很简单Rust 的生命周期与泛型参数在运行期不可见而 Python 是引用计数的动态语言无法给 Rust 编译器提供任何关于对象存活时长的保证因此唯一正确的要求就是#[pyclass]不借用任何短于static的数据并且整个类型可以安全地跨线程共享。默认行为内部可变性与运行时借用检查#[pyclass]默认采用与std::cell::RefCellT极为相似的内部可变性模式在任意时刻要么允许多个共享引用T同时访问数据要么允许一个独占引用mut T访问数据二者不可同时存在。PyO3 通过PyT与Boundpy, T这两个智能指针在运行时跟踪借用状态相关机制在指南的 Bound 与内部可变性 一节有完整示例。对于简单的类这套机制可以让它自动满足线程安全代价是每次访问都要做运行时检查# use pyo3::prelude::*; #[pyclass] struct MyClass { x: i32, y: i32, } #[pymethods] impl MyClass { fn get_x(self) - i32 { self.x } fn set_y(mut self, value: i32) { self.y value; } }上述类在单线程下没有任何问题但如果在两个不同的 Python 线程中同时调用get_x需要self共享借用与set_y需要mut self独占借用借用发生重叠时至少有一个线程会抛出一个指示数据已被借用already borrowed的运行时错误。这一点在仓库测试中有直接印证tests/test_inheritance.rs 的mutation_fails测试通过让一个方法在持有可变借用期间回调另一个方法最终断言抛出的异常文本正是RuntimeError: Already borrowed。默认的运行时检查对大多数低并发的简单类足够安全但它有两个问题一是在高并发下会产生可观的运行时开销二是借用重叠时会直接报错而非排队等待。这正是下面三种方案要解决的问题。特殊情况用unsendable退出线程安全约束在极少数场景下你可以确定自己的 Python 应用永远不会使用线程这种情况在实践中非常罕见。此时可以通过#[pyclass(unsendable)]主动退出Send/Sync约束代价是一旦发生跨线程访问会变成运行时 panic而非编译错误。# use pyo3::prelude::*; #[pyclass(unsendable)] struct MyClass { x: i32, y: i32, }unsendable在 pyclass 参数表 中有明确的配套警告与其使用unsendable更推荐用线程安全的方式重写你的结构体例如把Rc替换为Arc同时要注意 Python 的垃圾回收器本身是多线程的虽然unsendable类不会被放在其他线程上遍历以避免未定义行为但这可能导致内存泄漏。从源码看该机制由 src/impl_/pyclass.rs 中的ThreadChecker实现当类型实现Send时使用一个什么都不做的桩stub当类型不实现Send且被标记为unsendable时ThreadChecker会在该类型被其他线程访问或销毁时 panic通过 panic 来保证把T: !Send暴露给 Python 解释器仍然是安全的。仓库测试 tests/test_class_basics.rs 给出了典型用法——用unsendable包装一个包含std::rc::Rcusize字段的类# use pyo3::prelude::*; #[pyclass(unsendable, subclass)] struct UnsendableBase { value: std::rc::Rcusize, }同文件的panic_unsendable_base、drop_unsendable_elsewhere等测试验证了两种 panic 信息访问时是... is unsendable, but sent to another thread跨线程 drop 时是... is unsendable, but is being dropped on another thread。只有当你能对应用绝无多线程给出强保证时才建议使用该选项否则请始终构造真正线程安全的类型下面三种方案就是为此准备的。方案一使用原子数据结构frozenAtomic*要彻底消除self与mut self重叠导致运行时错误的可能一种思路是根本不使用mut self声明类为#[pyclass(frozen)]表示类不可变PyO3 不再对其做默认的运行时借用检查然后把需要修改的字段换成标准库的原子类型通过原子操作直接控制修改。例如将前面MyClass改造成原子版本# use pyo3::prelude::*; use std::sync::atomic::{AtomicI32, Ordering}; #[pyclass(frozen)] struct MyClass { x: AtomicI32, y: AtomicI32, } #[pymethods] impl MyClass { fn get_x(self) - i32 { self.x.load(Ordering::Relaxed) } fn set_y(self, value: i32) { self.y.store(value, Ordering::Relaxed) } }注意这里的set_y接收的是self而不是mut self因为原子类型允许在共享引用下进行安全修改。Ordering的选择取决于你的同步需求Relaxed适合单纯的计数器/标记位需要可见性保证时则应考虑Acquire/Release或SeqCst。frozen参数在 pyclass 参数表 中的说明是它移除了获取 Rust 结构体共享引用时的借用检查开销但同时禁用获取可变引用的能力。正因如此它常与原子类型、Mutex这类自带内部可变性的容器搭配使用。原子方案的开销极低无锁、无系统调用特别适合计数器、标志位、ID 分配这类细粒度场景。它的局限也很明显只能覆盖单字段、单数值的简单修改无法表达多字段之间需要一致性的复合操作。方案二使用锁Mutex让线程排队等待与原子类型互补的另一条路线是使用标准库的Mutex让想要访问共享数据的线程排队等待而不是在借用重叠时报错。将整个数据包进一个Mutex类本身标记为frozen# use pyo3::prelude::*; use std::sync::Mutex; struct MyClassInner { x: i32, y: i32, } #[pyclass(frozen)] struct MyClass { inner: MutexMyClassInner } #[pymethods] impl MyClass { fn get_x(self) - i32 { self.inner.lock().expect(lock not poisoned).x } fn set_y(self, value: i32) { self.inner.lock().expect(lock not poisoned).y value; } }这里的expect(lock not poisoned)处理了 Rust 标准库互斥锁的中毒poisoning语义如果持锁线程在持有锁期间 panicMutex会进入中毒状态后续lock()会返回Err。如果你的业务允许在中毒后继续使用数据也可以调用into_inner()显式忽略中毒状态PyO3 内部在 src/platform/sync.rs 的non_poison模块中就是这样做的。Mutex方案的优点是表达能力完整、天然支持跨多字段的一致性操作缺点是有锁竞争开销且需要小心地控制临界区范围避免在持锁期间做耗时操作。在持有锁的同时调用 PythonMutexExt与lock_py_attached如果你需要在持有锁的同时锁定存储在 Python 解释器中的状态或者需要调用 Python C API普通的Mutex::lock()可能造成与 GIL全局解释器锁或其他全局同步事件的死锁。PyO3 为此提供了MutexExt扩展 trait它为std::sync::Mutex提供了lock_py_attached方法用于规避这类死锁。从源码看MutexExt定义在 src/sync.rs其实现逻辑很直接先尝试try_lock()快速路径只有在确实需要阻塞等待时才通过内部SuspendAttach机制先从 Python 运行时分离detach完成加锁后再重新挂接reattach。之所以要这样做是因为 Python 解释器存在多种stop the world场景GIL 构建下的全局解释器锁、垃圾回收器暂停挂接线程等如果线程在持锁阻塞的同时仍挂在 Python 运行时上就可能与解释器形成互相等待的死锁——而 detach 之后再阻塞就不会卡住解释器自身。src/sync.rs的模块级文档对这一设计动机有完整说明。除了MutexExtPyO3 还在 src/sync.rs 中提供了一系列配套扩展它们遵循同样的 detach/reattach 思路OnceExt为Once提供call_once_py_attached/call_once_force_py_attachedOnceLockExt为std::sync::OnceLock提供get_or_init_py_attachedRwLockExt为std::sync::RwLock及lock_api::RwLock提供read_py_attached/write_py_attached。这些扩展的完整测试用例包括双线程 Barrier 同步、验证阻塞期间的正确性也都在 src/sync.rs 的tests模块中。启用parking_lot、lock_api与arc_lock特性除了标准库的同步原语PyO3 还通过三个 Cargo 特性扩展了支持的锁库见根目录 Cargo.tomlparking_lot为parking_lot类型提供OnceExt与MutexExt实现该特性依赖lock_api即parking_lot [dep:parking_lot, lock_api]lock_api为lock_api::Mutex、lock_api::ReentrantMutex、lock_api::RwLock等提供对应的MutexExt/RwLockExt实现arc_lock当你需要lock_api以及parking_lot的arc_lock能力即通过Arc持锁、返回ArcMutexGuard等时启用定义见 Cargo.toml 中的arc_lock [lock_api, lock_api/arc_lock, parking_lot?/arc_lock]。三个特性均可叠加使用parking_lot/lock_api被收录在full特性集合中arc_lock同样在列说明它们是官方推荐的组合。启用后例如parking_lot::Mutex、Arcparking_lot::Mutex就都能调用lock_py_attached了。方案三手动包装非线程安全数据某些情况下#[pyclass]内部存储的数据结构本身就不是线程安全的例如包含Rc、裸指针或非Send的第三方类型此时 Rust 不会为#[pyclass]类型自动实现Send与Sync编译就会失败。要达成线程安全需要手动实现Send和Sync。由于这两者在 Rust 中都是unsafe trait手动实现属于 unsafe 操作必须在对实现的健全性soundness做过仔细审查后才能进行# use pyo3::prelude::*; struct NotThreadSafe { // ... 某些非 Send/Sync 的数据 } struct MyClass { inner: NotThreadSafe, } // SAFETY: 必须通过严格审查确认所有访问路径都不会产生数据竞争。 unsafe impl Send for MyClass {} unsafe impl Sync for MyClass {}对于 PyO3 类型这一做法的要求与任何其他 Rust 代码完全一致没有特殊捷径。判断unsafe impl Send/Sync是否健全的核心问题是能否保证同一时刻最多只有一个线程写、允许多线程读且读不并发于写。如果内部数据在unsafe impl Sync之后仍然可能被两个线程同时写那么这个实现就是不健全的会引入未定义行为。Rust 官方文档The Rustonomicon 的 Send and Sync 章节对这类问题有深入讨论动手前建议先完整阅读并对照检查自己的类型。这是三种方案中风险最高的一种应作为最后手段且必须辅以充分的并发测试。三种方案如何选择| 方案 | 核心手段 | 适用场景 | 注意点 | | :- | :- | :- | :- | | 原子数据结构 |#[pyclass(frozen)]Atomic*字段 | 计数器、标志位、单数值高频读写 | 无法表达跨字段一致性的复合修改 | | 锁Mutex/RwLock |#[pyclass(frozen)] 锁保护内部数据 | 结构体级别的读写、需要复合一致性 | 有锁竞争开销持锁调用 Python 需用lock_py_attached等扩展方法 | | 手动unsafe impl Send/Sync| 包装非线程安全数据结构 | 无法改造成线程安全的数据结构 | 必须严格审查健全性风险最高 |综合来看PyO3 的线程安全实践遵循一条清晰的路径默认内部可变性模式让简单类开箱即安全代价是运行时检查与可能的Already borrowed错误当并发真实存在时优先用frozen配合原子类型或锁显式接管并发控制只有当数据结构本身无法线程安全化时才在严格审查后使用unsafe 手动实现。而unsendable只是针对确定永不多线程特例的逃生舱并且要接受跨线程 panic 与 GC 内存泄漏的代价——它绝不应成为常规选择。这套机制连同MutexExt/RwLockExt等扩展一起构成了 PyO3 在多线程 Python 应用中的完整并发安全基础设施。【免费下载链接】pyo3Rust bindings for the Python interpreter项目地址: https://gitcode.com/gh_mirrors/py/pyo3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考