Sapling/Mononoke 代码规范：Async Mutex Guard Across Await —— 禁止持有同步锁跨越 `.await` 点

• 开发工具
• CLI
• 后端

本篇技术指南基于 async_mutex_guard.md 规则文档，深入讲解 Rust 异步代码中同步互斥锁（std::sync::Mutex/RwLock）的守卫（Guard）跨越.await点这一 CRITICAL 级别的代码审查规则：它是什么、为什么严重、如何识别、如何修复，以及 Meta 开源版本控制系统 Sapling/Mononoke 仓库中对应的真实工程实践与源码佐证。读完本文，你将掌握在 async Rust 项目中安全使用锁的完整心法，并能直接用这套规则审查自己的代码。

规则背景：这条规则从哪来

async_mutex_guard.md位于 eden/.llms/rules/async_mutex_guard.md，是仓库中AI/LLM 代码审查规则集（.llms/rules）的一员。该目录下还收录了 case_sensitivity.md、config_rollout_safety.md、rust_unwrap_safety.md、unbounded_concurrency.md 等一系列面向 source_control 团队的静态审查规则。

规则文档的 YAML 元数据（front matter）定义了其适用范围：

也就是说，这条规则自动扫描eden/mononoke/与eden/scm/下的 Rust 文件，只要出现Mutex::lock()、RwLock::read()、RwLock::write()等调用就会触发审查，属于自动化、强制性的代码质量关卡，而非仅供参考的软性建议。

规则核心：什么情况下会被标记

需要标记（Flag）的情况

规则明确指出以下模式是问题：

1. MutexGuard/RwLockReadGuard/RwLockWriteGuard在遇到.await时仍然存活（未被 drop）——即锁的守卫对象跨越了异步挂起点；
2. let guard = mutex.lock()之后、guard被 drop 之前，代码中出现了任意.await；
3. 在异步代码中使用std::sync::Mutex（如果守卫必须跨越 await，应该改用tokio::sync::Mutex，或者把临界区收窄到不跨越 await）。

不标记（Do NOT Flag）的情况

规则的例外条款同样重要，避免误报：

1. 守卫在.await之前已经释放。例如把锁限定在块作用域内：{ let g = m.lock(); val = g.clone(); }，随后再执行val.do_async().await——此时锁早已随块结束而释放；
2. 刻意使用tokio::sync::Mutex并附注释说明原因；
3. 纯同步代码路径（作用域内没有async fn也没有.await）。

为什么这是 CRITICAL：同步锁跨 await 的致命后果

要理解这条规则为什么被评为CRITICAL，需要回顾 Rust 异步运行时的一个基本事实：

• std::sync::Mutex的lock()是阻塞式的，返回的MutexGuard不实现Send；
• 在异步代码中，.await意味着当前任务可能把执行权交还给运行时，由其他任务在其他线程上继续执行该 Future；
• 如果守卫跨越.await，编译时就会直接报错（future cannot be sent between threads safely），或者即使侥幸通过编译（如单线程运行时 / 非Send场景），也会造成严重的死锁与性能风险：
  • 当一个任务在持有锁时被挂起，而它等待的异步操作（如fetch_from_store）恰好需要另一个任务完成，而那个任务又试图获取同一把锁，就会形成跨任务的长期持锁阻塞——其他任务只能排队等待，而持锁任务可能长时间不会继续执行；
  • std::sync::MutexGuard不是Send的，一旦 Future 在持锁状态下被移动到其他线程，程序行为就变得不确定甚至直接 panic。

从 Rust 类型系统的角度看，同步MutexGuard不实现Send这一特性，本身就是编译器对"守卫不得跨越 await"的强制约束——这正是本规则存在的深层原因：让审查在编译之前就把问题拦下来。

规则文档给出的反面示例（BAD）

async fn update_cache(cache: &Mutex<HashMap<Key, Value>>, key: Key) -> Result<()> { let mut guard = cache.lock().unwrap(); let new_val = fetch_from_store(key).await?; // guard held across await! guard.insert(key, new_val); Ok(()) }

问题解析：cache.lock().unwrap()获取的MutexGuard在fetch_from_store(key).await执行期间仍然存活。这把锁会一直持有到函数结束才释放，跨过了整个 await 点——正是规则要消灭的模式。

规则文档给出的正确示例（GOOD）

async fn update_cache(cache: &Mutex<HashMap<Key, Value>>, key: Key) -> Result<()> { let new_val = fetch_from_store(key).await?; // lock() only returns Err on poison (prior panic) — unrecoverable, so expect is fine here let mut guard = cache.lock().expect("cache lock poisoned"); guard.insert(key, new_val); Ok(()) }

关键改进：先完成所有异步操作（fetch_from_store），再获取锁。锁的持有时间被压缩到纯同步的临界区内，不跨越任何.await，既消除了持锁挂起的风险，也让代码无需处理 PoisonError——规则文档中的注释点明：lock()仅在**此前发生过 panic（锁被毒化）**时才返回Err，此时程序已处于不可恢复状态，因此expect("cache lock poisoned")是恰当的选择（这条思路与仓库中另一条规则 rust_unwrap_safety.md 一脉相承）。

修复策略：推荐的三种重构手法

规则在Recommendation一节给出了明确的修复路线，按优先级排列：

策略一：先 await，后加锁（推荐）

把所有异步调用前移到获取锁之前。这是最简单、最彻底的方案——锁的持有完全限制在同步临界区，类型系统与运行时都绝对安全，也是上述 GOOD 示例采用的方式。

策略二：acquire-copy-release（获取-拷贝-释放）

如果临界区逻辑复杂、无法简单前移异步调用，可以在 await 之前短暂持锁读取所需数据，释放锁后再进行异步计算，最后重新加锁写入结果：

async fn update_cache(cache: &Mutex<HashMap<Key, Value>>, key: Key) -> Result<()> { // 短暂加锁：只做同步拷贝 let (old_value, clone_needed) = { let guard = cache.lock().unwrap(); (guard.get(&key).cloned(), true) // 拷贝后，块结束即释放锁 }; // 锁已释放，可以安全 await let new_val = fetch_from_store(key).await?; // 重新加锁写入 let mut guard = cache.lock().unwrap(); guard.insert(key, new_val); Ok(()) }

这种模式的关键在于利用块作用域隐式释放锁——锁的生命周期被严格限定在不需要 await 的同步代码段内。代价是可能需要重复加锁/解锁，但换取的是绝对的安全性。

策略三：改用tokio::sync::Mutex并附注释

如果锁必须跨越 await（例如保护一个跨多次 await 的长生命周期状态机），则使用异步运行时提供的tokio::sync::Mutex。它的守卫是 await 安全的，lock().await本身就是挂起点，不会阻塞线程。但规则强调：必须附加注释说明设计原因，因为默认方案仍应是"避免跨 await 持锁"，而非无脑换锁。

tokio::sync::Mutex与std::sync::Mutex的本质区别在于：前者在任务被挂起时会释放底层资源、允许运行时调度其他任务，锁的等待队列由 tokio 运行时管理；后者在持锁期间若发生 await，整个线程都可能被锁拖住。这也是"async 代码里默认用tokio::sync::Mutex"这一社区共识的底层原理。

仓库源码佐证：Mononoke 中的两种正确用法

规则不是空谈——在 Mononoke 的实际代码中，可以同时找到"同步锁严格限定在同步代码内"和"刻意使用 tokio Mutex 跨 await"这两类正确范例。

范例一：同步锁std::sync::Mutex仅用于同步临界区

在 virtually_sharded_blobstore/src/lib.rs 的shared_read函数中，large_inflight_reads.lock().unwrap()获取的同步MutexGuard被严格限定在一个立即求值的块作用域内——let inflight_read = { let mut large_inflight_reads = inner.large_inflight_reads.lock().unwrap(); ... }。所有锁操作（查询、插入、删除）都是纯同步的 HashMap 操作，块结束后守卫立即释放，之后才执行ticket.finish().await与inner.blobstore.get(&ctx, &key).await。这正是规则文档"守卫在.await之前 drop（scoped in a block）"这一例外条款的教科书式应用。

类似地，blobstore/test_utils/lib.rs 中测试工具Tickable::tick/drain/on_tick使用self.queue.lock().unwrap()，但都只做同步的队列读写后立即释放，锁从不跨越其返回的 Future。

范例二：刻意使用tokio::sync::Mutex跨 await

Mononoke 仓库中有多处正确使用tokio::sync::Mutex的范例，它们都有一个共同点：守卫确实跨越了 await，因此必须用异步锁。

用例 A：内存租约表（in-process lease）。在 in_process_lease.rs 中，InProcessLease用Arc<Mutex<HashMap<...>>>（tokio::sync::Mutex）保护租约表，try_add_put_lease、wait_for_other_leases、release_lease等async方法都通过self.leases.lock().await获取守卫。这里锁的语义本身涉及Sender/Shared<Receiver>等异步唤醒通道，持锁期间虽然都在做同步 HashMap 操作，但选择 tokio Mutex 保证了整条异步链路的 await 安全性。

用例 B：单飞刷盘锁（flush single-flight）。在 mem_writes.rs 中，MemWritesBlobstore维护了两把锁：cache: Arc<Mutex<Cache>>（std::sync::Mutex，用于保护内存缓存本身）和flush_mutex: Arc<AsyncMutex<()>>（tokio::sync::Mutex，用于保证同一时刻只有一个任务在执行刷盘）。代码注释明确写道："Mutex to ensure only one task is flushing the cache at a time. Note: this doesn't wrap the cache as read access is permitted while the mutex is held."——在persist()（mem_writes.rs）中，let _flush_guard = self.flush_mutex.lock().await获取的守卫横跨了整个异步刷盘过程（flush.buffered(4096).try_for_each(...).await），因此必须使用 await 安全的 tokio Mutex。两把锁职责分明：同步锁管短小临界区，异步锁管跨 await 的长事务——这是对规则"用对锁、用对场景"最精确的工程诠释。

用例 C：单飞 reconcile 守卫。在 repos_manager.rs 中，run_exclusive使用tokio::sync::Mutex<()>实现单飞（single-flight）语义：lock.try_lock()成功才执行body().await，否则直接跳过不排队。函数注释明确指出："The tokio Mutex is await-safe, so the guard is intentionally held acrossbody's await."——这是规则文档"用tokio::sync::Mutex并且附注释说明设计选择"这一例外条款在仓库中的直接体现。

这三个用例展示了一个清晰的决策矩阵：临界区是纯同步且短暂 → 用std::sync::Mutex并保证不跨 await；临界区必须跨越 await → 用tokio::sync::Mutex并写注释；既想持锁跨 await 又想避免排队 →try_lock单飞模式。

与相关规则的协同

这条规则与同目录下的其他规则共同构成 Mononoke/Sapling Rust 代码的并发与安全审查体系：

• rust_unwrap_safety.md：处理unwrap/expect的使用边界。上文 GOOD 示例中的expect("cache lock poisoned")正是两条规则交叉的典型案例——由于锁毒化不可恢复，expect比unwrap更能表达意图；
• unbounded_concurrency.md：约束无界并发。mem_writes.rs中flush.buffered(4096)的固定缓冲上限，就是有界并发的具体实现；
• sequential_blobstore_fetches.md 与 repeated_large_traversal.md：关注 blobstore 与遍历操作的异步调用模式，与锁规则共同保证异步代码既不死锁、也不浪费吞吐。

规则落地：如何把检查嵌入日常开发

对于 Sapling/Mononoke 的贡献者，以及任何想把这套规则引入自己项目的开发者，实践路径如下：

1. 人工审查时对照三问：当前锁守卫的持有范围是否跨越.await？是否能在 await 前释放？若不能，是否已改用tokio::sync::Mutex并注释原因？
2. 借助编译器的力量：std::sync::MutexGuard不实现Send，在多线程运行时（如 tokio 的multi_thread模式）下，跨 await 持锁的 Future 会导致Send约束检查失败，cargo build/cargo check即可捕获大部分违规；
3. 接入静态审查：参考本仓库 .llms/rules 的组织方式，把async_mutex_guard.md这类规则文档纳入团队的代码审查或 LLM 辅助审查流程，利用apply_to_path/apply_to_content元数据实现自动化扫描；
4. 审查现有代码时注意例外：块作用域内及时释放的锁、带注释的 tokio Mutex、纯同步路径都不应被标记，避免"矫枉过正"引入无谓重构。

总结

Async Mutex Guard Across Await是一条以类型系统原理为根基的 CRITICAL 级并发规则：同步锁的守卫跨越.await，要么在编译期被Send约束拦截，要么在运行期引发跨任务持锁与死锁风险。正确的姿势永远是——先 await，后加锁；必须跨 await 时用tokio::sync::Mutex并注明原因。Mononoke 仓库中的 in_process_lease.rs、mem_writes.rs 与 repos_manager.rs 分别展示了同步锁短临界区、异步锁跨事务、try_lock单飞三种正确范式，可作为任何 async Rust 项目的对照模板。

• 开发工具
• CLI
• 后端