Skip to main content

Crate napart

Crate napart 

Source
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§

FrozenEvidence
不持有业务载荷的任务冻结证据。
FrozenEvidenceSnapshot
有界冻结诊断快照。
PartitionExecutor
standalone 自管兼容执行器。
PartitionRunner
可克隆的命名 Runner 控制句柄。
PartitionRunnerRegistry
显式拥有的命名 Runner 注册表。
PartitionRunnerRegistryBuilder
注册表构造器。
RouteHash
不透明的进程内路由值;不写入持久化协议,也不接受 Redis 物理分区哈希。
RunnerConfig
单个 Runner 的完整冻结配置。
RunnerMetricsSnapshot
Runner 当前指标快照;全部字段都是低基数累计值或资源瞬时值。
RunnerName
已校验、可用于指标标签和注册表索引的稳定 Runner 名称。
ShutdownReport
停机损耗与退出证明摘要。
StopAllEntry
stop_all 中单个 Runner 的稳定结果。
StopAllReport
注册表聚合停止报告。
Submission
分区任务的稳定终态句柄。
TaskSpec
提交规格:稳定任务类型与不可变顺序要求。
TaskType
任务类型:严格顺序、路由和低基数指标的稳定索引。

Enums§

ForceStopError
显式有损停止没有在调用方期限内取得完整退出证明。
RunnerHealth
Runner 健康状态;该值用于 readiness,不是进程 liveness 探针。
RunnerPhase
Runner 生命周期阶段。
RunnerRegistryError
命名 Runner 注册或查询失败。
StartError
Runner 启动失败。
StopError
无损停止没有在调用方期限内取得完整退出证明。
SubmitError
非阻塞兼容提交被拒的原因。
SubmitRejection
类型化提交被拒的稳定原因。
TaskOrdering
任务顺序要求。
TaskStatus
任务在公开句柄中的生命周期状态。

Constants§

DEFAULT_RUNNER
兼容入口和受管 Application 默认使用的稳定 Runner 名称。

Type Aliases§

MetricsSnapshot
兼容旧执行器公开名称的指标别名。