Expand description
命名隔离、严格 FIFO,并通过盗洞完成保序任务窃取的分区任务执行器。
§核心价值
每个 PartitionRunner 是独立的有界执行域:名称、generation、slot、主 MPSC 队列、类型
状态、盗洞、延迟索引、容量、指标、健康和停机互不共享。严格顺序边界是“Runner + 原始
分区 + TaskType”;任务跨 slot 迁移与归还时仍使用同一受理序号,因此 stock、incremental
和 staging 的物理切换不会改变 FIFO。
每个分区只有一个主 SequencedMpsc consumer。集中 observer 只向源 worker 发布
窃取请求,只有源 worker 能安装盗洞和移动主队列存量。非严格类型允许多目标租约盗洞;严格
类型只有一个盗洞,并分离存量、增量和归还暂存 FIFO。任何无法证明 owner、物理位置或顺序
的状态都会关闭最小故障域并留下有界证据。
§背压、延迟与观测
接入层可通过 RouteHash::from_key 冻结业务键,再调用
PartitionRunner::submit_routed_typed;路由摘要只用于本地执行,不是持久分片协议。
不同 Runner 不自动建立顺序关系;持久消息接入层须另外维护跨域 ACK、重试与顺序门禁。
每个 Runner 分别限制类型排队量、全局在飞量、类型状态数和目标入站盗洞数。非阻塞提交会以
稳定 SubmitRejection 表示容量或控制门禁;等待型提交按固定次序取得许可并保持取消安全。
PartitionRunner::submit_after 登记时只占全局许可,到期后才竞争类型容量,因此登记成功的
delayed 任务仍可能以 TaskStatus::Rejected 结束。取消和到期重新准入只能有一个稳定终态,
许可与排队投影只结算一次,拒绝指标只记录实际取得拒绝权威的路径。
PartitionRunner::metrics_snapshot 提供 Runner 级容量、队列、timer、moving、盗洞、终态、
拒绝分类与停止损耗;Submission::await_outcome 和稳定 reason 用于逐任务证明。
§接入方式
直接动态模式由业务持有一个进程级 PartitionRunnerRegistry,运行期间可以按稳定名称调用
PartitionRunnerRegistry::get_or_create 并显式启动。名称身份只在同一注册表内成立;为每次请求
新建注册表会创建互不相干的执行域。调用方必须保留注册表或 Runner 控制句柄,并负责确定停机。
napp 或 nasa 的 Application 受管模式在 Service UserHook 结束时冻结 YAML 与代码计划,随后
于 Prepare 统一启动并发布不含启停权的业务句柄。该模式负责 readiness 与反序停机,但不在 Running
阶段增加 Runner;运行期才确定执行域的业务应选择直接动态模式。
§生命周期
命名调用方显式拥有 PartitionRunnerRegistry,取得 Runner 后调用 PartitionRunner::start。
PartitionRunner::stop 只做无损收口,期限不足会保持 Stopping 并返回错误;只有显式
PartitionRunner::force_stop 才允许中止与冻结。生命周期动作由常驻 supervisor 推进,公开
等待 Future 被取消不会撤销已经发布的动作。最后一个控制句柄析构只触发无等待的有损兜底,
不提供退出证明;需要确定结果的调用方必须显式停止。
PartitionExecutor 是不进入共享注册表、构造时立即启动的 standalone 兼容包装。新代码若
需要多个隔离执行域,应使用命名 Runner。
§能力边界
Runner 之间隔离调度状态、容量、健康和生命周期,但共享调用方提供的 Tokio runtime,不提供 CPU、进程内存或故障域的硬隔离。napart 也不提供跨进程接管、持久化队列、至少一次投递或进程 崩溃恢复;单个严格顺序方向始终只有一个业务任务执行权。
Structs§
- Frozen
Evidence - 不持有业务载荷的任务冻结证据。
- Frozen
Evidence Snapshot - 有界冻结诊断快照。
- Partition
Executor - standalone 自管兼容执行器。
- Partition
Runner - 可克隆的命名 Runner 控制句柄。
- Partition
Runner Registry - 显式拥有的命名 Runner 注册表。
- Partition
Runner Registry Builder - 注册表构造器。
- Route
Hash - 不透明的进程内路由值;不写入持久化协议,也不接受 Redis 物理分区哈希。
- Runner
Config - 单个 Runner 的完整冻结配置。
- Runner
Metrics Snapshot - Runner 当前指标快照;全部字段都是低基数累计值或资源瞬时值。
- Runner
Name - 已校验、可用于指标标签和注册表索引的稳定 Runner 名称。
- Shutdown
Report - 停机损耗与退出证明摘要。
- Stop
AllEntry stop_all中单个 Runner 的稳定结果。- Stop
AllReport - 注册表聚合停止报告。
- Submission
- 分区任务的稳定终态句柄。
- Task
Spec - 提交规格:稳定任务类型与不可变顺序要求。
- Task
Type - 任务类型:严格顺序、路由和低基数指标的稳定索引。
Enums§
- Force
Stop Error - 显式有损停止没有在调用方期限内取得完整退出证明。
- Runner
Health - Runner 健康状态;该值用于 readiness,不是进程 liveness 探针。
- Runner
Phase - Runner 生命周期阶段。
- Runner
Registry Error - 命名 Runner 注册或查询失败。
- Start
Error - Runner 启动失败。
- Stop
Error - 无损停止没有在调用方期限内取得完整退出证明。
- Submit
Error - 非阻塞兼容提交被拒的原因。
- Submit
Rejection - 类型化提交被拒的稳定原因。
- Task
Ordering - 任务顺序要求。
- Task
Status - 任务在公开句柄中的生命周期状态。
Constants§
- DEFAULT_
RUNNER - 兼容入口和受管 Application 默认使用的稳定 Runner 名称。
Type Aliases§
- Metrics
Snapshot - 兼容旧执行器公开名称的指标别名。