V 语言 x.executor 模块本地验证工具链实战：check_no_async_dependency.sh 与 validate.sh 全解析

x.executor 是 V 语言仓库（vlib/x/executor）中一个"窄而明确"的 owner-loop 执行器模块，而 vlib/x/executor/tools/README.md 专门描述了围绕它构建的两套本地辅助脚本：依赖守卫 check_no_async_dependency.sh 与受控验证入口 validate.sh。本文以该文档为主线，结合脚本源码与模块测试，完整讲解这两套脚本的设计动机、实现细节与正确用法，帮助你在本地 V 检出中安全、可复现地完成 x.executor 的格式化、示例、常规测试与 -prod 测试验证。

为什么 x.executor 需要"受控验证"

x.executor 是一个由 owner 线程主动泵取回调的轻量执行器：调用方可以把短回调提交给持有某资源的线程或循环，而无需暴露调度器内部、也无需启动隐藏运行时。它刻意保持依赖面极窄——不依赖 GUI、渲染、音频、网络或任何调度器，并且是 x.async 的"兄弟模块"而非其上层，模块自身绝不 import x.async，vlib/x/executor/examples 中的示例也只使用合成本地工作、spawn、channel、context 和 time。

正因如此，任何把 x.async 悄悄引入模块或示例的改动，都会破坏"无隐藏运行时、无调度器依赖"的模块契约。tools 目录下的两个脚本正是为守住这条边界而生：

• check_no_async_dependency.sh：执行独立依赖规则（standalone dependency rule）的静态守卫；
• validate.sh：串行、隔离地运行完整的守护验证路径。

tools/README.md 同时给出了两条硬性约束：脚本必须使用仓库相对路径，且不得依赖本机路径、密钥或外部服务——这让验证结果在任何共享检出/缓存环境下都可复现。

依赖守卫：check_no_async_dependency.sh 的三道检查

从仓库根目录执行：

sh vlib/x/executor/tools/check_no_async_dependency.sh

脚本开头通过 CDPATH= cd "$(dirname "$0")" && pwd 与逐级 ../.. 解析出仓库根目录并 cd 进去（check_no_async_dependency.sh），从而保证"从任何目录调用都能得到一致结果"。随后对目标目录 vlib/x/executor 执行三道检查，任何一道失败都会在 stderr 打印具体命中行并以退出码 1 终止：

1. 模块源码禁止导入 x.async：用 find ... -name '*.v' 配合 grep -n 'import x\.async' 扫描模块内所有 V 源文件（第 15-21 行）。命中即报 x.executor must not import x.async: 并列出具体文件与行号。

2. 示例不得提及或使用 x.async：若存在 examples 目录，则对其中所有文件执行 grep -n 'x\.async'（第 23-29 行）。注意这里不限定 .v 后缀，连示例里出现在注释或字符串中的 x.async 也会被拦截。

3. 模块内不得出现 async/bridge 命名的 V 源文件：用 grep -Ei '(^|/)(async|.*bridge.*)\.v$' 对文件全路径做文件名级检查（第 31-37 行），从命名层面杜绝"伪装成桥接文件"的异步实现混入模块。

全部通过时输出 x.executor dependency check passed。临时中间文件写入 /tmp/xexecutor_async_*.$$ 并在每步检查后立即清理，脚本整体以 set -eu 运行，任何命令失败都会立即暴露。

受控验证入口：validate.sh 的五个阶段

同样从仓库根目录执行：

sh vlib/x/executor/tools/validate.sh

validate.sh 首先强制要求当前检出存在可执行的本地 ./v（validate.sh），否则直接报错退出——它只服务于 V 仓库检出环境。随后依次执行五个阶段（第 34-46 行）：

阶段	命令	超时	作用
1. 依赖守卫	sh vlib/x/executor/tools/check_no_async_dependency.sh	—	拦截任何 x.async 依赖泄漏
2. 格式校验	./v fmt -verify（模块全部 .v 文件）	60s	保证模块代码符合 V 官方格式
3. 示例串行运行	对 examples/ 下每个公开示例依次 ./v run	每个 60s	防止示例"bit rot"
4. 常规测试	./v test vlib/x/executor	120s	模块全部测试（含并发/压力/生命周期用例）
5. 生产模式测试	./v -prod test vlib/x/executor	180s	以优化模式复跑测试，暴露 release 路径问题

示例运行采用逐个串行方式，而不是一次性并行：脚本用 find ... | sort 得到稳定的文件清单（第 36-37 行），再在 for 循环中逐个 run_v 60 run "$example"。

隔离与串行化：VTMP、VCACHE 与本地 ./v

validate.sh 的核心工程价值在于环境隔离 + 严格串行（第 13-32 行）：

• 通过 mktemp -d "${TMPDIR:-/tmp}/xexecutor-validate.XXXXXX" 创建全新临时根，并注册 trap cleanup EXIT INT TERM 保证退出时清理；
• 在临时根下建立独立的 vtmp 与 vcache 目录，所有 V 命令都通过 env VTMP="$vtmp" VCACHE="$vcache" ./v ... 运行；
• 统一使用仓库本地 ./v，绝不依赖全局安装的 V；
• 所有阶段共用同一个 run_v 辅助函数，在系统存在 timeout 命令时施加硬超时，防止某个示例或测试永久挂死（第 23-32 行）。

这样设计的原因在文档中写得很清楚：当多个外部 runner 共享同一个检出/缓存时，V runner 的产物与缓存会互相碰撞。隔离 VTMP/VCACHE 并串行执行，从根源上消除这类竞态。

崩溃信号的处理原则

tools/README.md 特别强调：如果崩溃出现在这条串行化、隔离化的路径上，应视为阻塞性的运行时/测试信号（blocking runtime/test signal），不得未经重新调查就归咎为工具噪音。换句话说，validate.sh 排除了缓存污染、并行干扰等外部因素之后，剩下暴露的问题基本都可复现、值得深挖。

与模块其余验证设施的分工

tools 目录并非孤立存在，它与模块的测试、示例、基准构成完整验证体系：

• 测试：v test vlib/x/executor 与 v -prod test vlib/x/executor 是功能与并发安全的最终权威；模块内已有 admission_test.v、config_test.v、owner_test.v、lifecycle_test.v、stress_test.v、sync_call_test.v 等用例覆盖。文档明确"回归保证存在于模块测试中"，示例只是文档优先（documentation-first）的程序。
• 示例：examples/ 目录的规则与工具守卫一致——不依赖 x.async、无真实 GUI/渲染/音频/FFI/网络依赖、无固定本地路径、不打开网络监听、避免用 panic() 做控制流、owner 回调刻意保持短小（见 examples/README.md）。你可以用 ./v run vlib/x/executor/examples/basic_post.v 等命令单独跑任一示例。
• 基准：benchmarks/ 同样坚持"串行化 + 隔离 VTMP/VCACHE"的设计（benchmarks/README.md），run_executor_benchmark.sh 用 ./v -prod -o 编译到临时输出二进制后运行，并通过 XEXECUTOR_BENCH_* 环境变量控制规模（所有值会被钳制）。文档强调基准只是观测工具，不是可移植的性能断言，测试才是权威。

错误契约：验证可断言的地基

脚本守卫的 x.async 禁令只是外部约束；模块内部还把全部公共错误字符串集中在 errors.v 中，因为它们是公共契约的一部分，须保持稳定、简短并显式限定到 x.executor：

const err_queue_full = 'executor: queue is full'
const err_queue_size_invalid = 'executor: queue size must be positive'
const err_owner_submit_wait = 'executor: owner thread cannot wait for queue capacity'
const err_timeout = 'executor: timeout'
const err_nil_job = 'executor: job function is nil'

测试（如 admission_test.v 中 assert err.msg() == 'executor: queue is full'）直接断言这些字符串，因此任何改动都必须保持稳定——这也是"受控验证"能可靠工作的前提之一。

实操要点与总结

• 日常快速验证：仅跑依赖守卫用 sh vlib/x/executor/tools/check_no_async_dependency.sh；完整验证用 sh vlib/x/executor/tools/validate.sh。
• 运行前提：两个脚本都要求从 V 仓库检出内执行，validate.sh 额外要求存在可执行的本地 ./v；脚本内部已自行 cd 到仓库根，因此从子目录调用也能工作。
• 不要在共享检出上并行跑多个 V 验证/基准：VTMP、VCACHE 与输出路径必须隔离，这正是 tools 与 benchmarks 脚本把隔离内建进去的原因。
• 把崩溃当回事：隔离路径上的失败意味着值得单独调查的可复现信号，而非工具噪音。

总而言之，check_no_async_dependency.sh 用三道 grep/find 静态检查守住了"不依赖 x.async"的模块边界，validate.sh 则用"本地 ./v + 临时 VTMP/VCACHE + 超时串行"的方式，把格式化校验、示例运行、常规测试与 -prod 测试组织成一条稳定、可复现、无缓存碰撞的守护流水线。这套"小脚本 + 明确契约 + 严格隔离"的验证模式，是 V 语言仓库工程化实践里一个非常值得借鉴的样例。