worker

package
v0.39.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

execute.go —— 单个在途任务的执行与收场(串行路径与并发池共用)。

从 loop.go 拆出的理由与 lease.go 同款(结构阈值按判据的一侧切): 领取/心跳是「怎么找到活」,本文件是「一条活怎么跑完、怎么落库」。

heartbeat.go —— 注册心跳与在途租约续期(issue #179/#196 共用的单拍循环)。

两个心跳、一拍执行、互不阻断

续期先做、注册心跳后做:身份的可用性不是任务正确性的前置条件—— 注册表抖动不得吞掉同一拍的租约续期(issue #179 的触发序列)。

并发面:按任务独立续期,失败逐个处置

在途集合是 `map[TaskID]*claimed`(见 loop.go 的 inflight)。每一拍对 **快照里的每一条**任务租约各做一次 Renew(Renew = 资格检查 + 推后到期):

  • 成功 → 该任务的连续失败计数清零;
  • ErrLeaseLost → 只取消**该任务**的在途 ctx(其它任务不受影响);
  • 其它错误 → 只累加该任务的计数;连续失败达到阈值(ErrLeaseUnconfirmed) 时按既有契约停止领取并取消该任务——答不出「谁在持」就不发起新的副作用。 停止领取会取消领取闸(claimCtx),已投递的在途任务走排水路径收场。

计数住在 claimed 上、只由本协程读写:任务移出集合后无人再碰,故无需 额外锁;在途集合本身由 inflight.mu 护住。

lease.go —— 在途租约资格的**可观测面**(issue #179):三条失去资格的 路径各给一个可判别的信号,宿主据此计数/留痕/告警。从 loop.go 拆出 (结构阈值按判据的一侧切):驱动循环与它的租约事件词表分开,两边各自 可读。

为什么这三条不许静默

「闸已易主、本次结果作废」是事实不是成功路径。静默吞掉它们,下游的 非幂等副作用就可能双份——租约易主 ⇒ 旧执行体本该被封口,而它是否 真被封口、收场有没有被拒,宿主必须有信号可看(@@Config.OnLeaseLost@@)。

loop.go —— 六段生命周期的驱动:注册 → 领取 → 执行 → 心跳/续期 → 排水 → 注销。

驱动不吞失败

每一段的失败都有**明确的处置**,不静默吞:

  • 注册失败 → 直接返回(没身份就别开工);
  • 心跳失败(@@ErrNotRegistered@@)→ 身份没了:停止领取,收刀退出; **非身份类**心跳失败(存储抖动)→ 只影响身份本身,**不得吞掉同一拍 的任务租约续期**(issue #179:身份的可用性不是任务正确性的前置条件 ——两个故障域互不阻断);
  • 任务租约续期失败(@@taskboard.ErrLeaseLost@@)→ 资格没了:**取消在途 执行的 ctx**,本次任务按失败收场——资格检查失败后的继续执行就是 与新持有者重复施加(危险窗口在施加之前封口);
  • 任务租约续期**连续失败**跨过一个 TTL(@@ErrLeaseUnconfirmed@@)→ 无法确认持有资格:取消在途 ctx + 停止领取收刀——续不上又继续开工, 与新持有者重复施加的是同一种危险,只是这次连「谁在持」都答不出来;
  • handler 失败 → 任务 Release 回任务板(failed/open 都可被重做, 一次失败不把子任务钉死——taskboard 的状态语义);
  • 收场动作被 @@taskboard.ErrLeaseLost@@ 拒(任务已归新持有者)→ 如实接受但**经 @@Config.OnLeaseLost@@ 留痕**——「闸已易主、本次结果 作废」是事实不是成功路径,静默吞掉它宿主就永远不知道丢了什么。

优雅退出 = 停止领取 + 在途收敛 + 注销

外层 ctx 取消后:不再领取新任务,**当前在途任务收场**(收场动作走 WithoutCancel——排水期间的 Complete/Release 不能因 ctx 已取消而失败), 然后注销注册。在途何时收敛由 handler 对 ctx 的响应决定:handler 无视 取消就等于无限期排水——ctx 已把「该收手了」送到它手里,剩下的不是 本驱动能替它决定的。

managed.go —— 受管任务执行器:Claim → SideEffect.Execute → Checkpoint → Complete 的标准编排。

它补的是哪一段(issue #191)

@@Loop@@ 的语义是「认领 → 调 Handler → 成功 Complete / 失败 Release」—— 失败即回板,可被重做。这条默认语义作用在**不可幂等**动作上就是重复施加: 下单、发信、改远程状态这类动作重跑一次,副作用就双份。

本执行器把「执行意图与对账」强制接进任务生命周期,四步不能重排、不能漏:

  1. **Claim**:拿租约与令牌(令牌由任务板铸造——任务归属的唯一凭据);
  2. **SideEffect.Execute**:走 @@sideeffect.Runner@@ 的既有契约—— Acquire 原子登记执行意图 + 栅栏令牌,施加前做持有资格检查, 失败按 @@RetrySafety@@ 分流出「可重试」与「结果未知」;
  3. **Checkpoint**:副作用记账成功后单调提交进度快照(不覆盖更高版本);
  4. **Complete**:凭第 1 步的令牌收口。

不发明第二套状态机

本执行器**只做编排**:每个判定都调用既有原语,不复制任何状态。

  • 「这次能不能做」归 @@sideeffect.Store.Acquire@@(已完成 / 结果未知 / 执行中 / 资源被占 / 授予);
  • 「这次失败能不能重试」归 @@sideeffect.RetrySafety@@ 与 Runner 的四条 失败出口(Abandon / MarkUncertain + Release);
  • 「进度回退」归 @@checkpoint.Committer@@(SaveIfNewer + 进程内闸);
  • 「任务归谁」归 @@taskboard.Board@@(令牌 + 代次,Complete 校验令牌)。

本文件出现 if/else 的地方都是**处置分流**(这个既有结论该触发哪个 既有动作),不是第四份判据。

UNCERTAIN 在任务板上的落法

taskboard 没有(也不该有)UNCERTAIN 状态:结果未知是 @@sideeffect@@ 的 一等结论,任务板只回答「谁负责这个子任务」。本执行器的处置是:

  • **不 Complete**(没做成的不能记成做成了);
  • **释放任务板租约**(不占着一把谁都不敢动的锁);
  • 该副作用 Key 由 sideeffect 闸继续挡着——任何 worker 重新认领后, Runner.Acquire 返回 OutcomeUncertain ⇒ 不执行、再次释放。于是 「任务可被重新认领」与「动作不会被重跑」同时成立,阻塞点在唯一 该在的地方(副作用闸),而不是在任务板上再长一个状态。

对账入口是 @@ManagedExecutor.Resolve@@(转发 Runner.Reconcile,不另造裁决)。

与 worker.Loop 的取舍

  • 任务动作**不可幂等**(或宿主不确定)→ 用本执行器。它保证失败/不确定 不会被「回板重做」变成重复施加;
  • 动作可安全重做、或根本不对接外部副作用 → 用 @@worker.Loop@@ 更省 (它已经处理注册、心跳、续期、优雅退出)。

两者不要叠着用:本执行器自己 Claim、自己 Complete,再套 Loop 的 Handler 会对同一任务二次收口(第二次必然 ErrLeaseLost)。

任务选择不在本执行器里

Execute 收的是**一个任务 id**(调用方选定)。优先级 / 公平 / 配额等挑选 判据归 @@scheduling@@——本执行器不内嵌第二份,否则同一件事会有两个答案, 而漂移的形态是「调度说该做 A、执行器挑了 B」且两边都显示正常。

memory.go —— Registry 的进程内参考实现(记忆版,**单进程演示用**)。

边界刻在类型上

MemRegistry 的原子性来自**进程内互斥锁**:Register 的「顶替 + 铸令牌」、 Heartbeat 的「资格校验 + 推后有效期」都在同一把锁内完成,但那只对同一 进程成立。多副本(多进程)共享注册表时,宿主要把同一套判据落到自己的 跨进程存储上(Redis SET NX PX / PostgreSQL 条件 UPDATE / etcd txn)—— 拿 MemRegistry 当多副本注册表,两个进程各持一把各自的锁, 「同 ID 顶替」「旧令牌心跳被拒」这些判据会显示为绿,而身份页实际上 已经不再一致(AGENTS.md「参考实现是可被误用的资产」那条纪律的原话场景)。

它在本仓的用途只有两个:①给 Loop 的契约用例当**测试保底**; ②给宿主当**形态示范**——照它的四个方法写跨进程版本(契约见 Registry)。

语义逐条

  • Register:同 ID 顶替并铸新令牌(崩溃重启是正常路径,先到者从此 被 ErrNotRegistered 拒在门外——它由此得知自己已被顶替,而不是靠 幽灵状态猜);
  • Heartbeat:令牌不匹配、记录不在、或有效期已过 ⇒ ErrNotRegistered (**不静默成功**);TTL <= 0 ⇒ ErrInvalidConfig;
  • Deregister:凭令牌;令牌不匹配 ⇒ ErrNotRegistered。过期的注册仍可 凭原令牌注销(收尾路径不该因为「刚好过期」而失败);
  • List:Alive 用**注册表自己的时钟**判(判据归存储侧,不归调用方); 过期记录保留在原地并显式 Alive=false——与 Registry.Status 的契约 一致(实现也可以清理,清理与否不是契约条款)。

pool.go —— 有界并发池(issue #196,Config.Concurrency > 1 的路径)。

形态:领取环单点、执行体有界并行

领取仍然只有一处(claimNext → Claim):并发认领会互相竞争同一个候选, 把「谁先领」变成随机重试;单点领取 + 并行执行拿到同样的吞吐,且 Pick 钩子不需要是并发安全的(既有契约不变)。

slots 是并发上限:领取前先占槽,认领到任务后把执行投给 async.GoSafe; 没有候选就立刻还槽并按 PollInterval 再试。因此慢任务只占执行槽, **不占领取环**。

排水(Drain)

停机 = 停止领取 + 等全部在途收场:

  • 外层 ctx 取消 ⇒ 主循环退出,执行体经派生 ctx 收到取消信号; 收场动作(Complete/Release)在 executeOne 里走 WithoutCancel, 落库不受停机影响;
  • 收场何时完成由 handler 对 ctx 的响应决定:handler 无视取消等于 无限期排水——这是既有 Loop 契约,不是并发池新增的语义。

失败处置

  • 执行体 panic → invokeHandler 收编为一次失败(Release),只影响该任务;
  • 收场(Complete/Release)返回基础设施错误 → 与串行路径同义:停止领取、 取消其它在途(它们按失败收场)、排水后把第一个错误交给 Run;
  • claimNext 的基础设施错误 → 同上(不再领取,等在途收场后返回)。

recover.go —— 任务恢复:接管前任留下的过期认领。

判资格不判时钟

「这个租约过期了吗」由**任务板自己的时钟与资格判定**回答(Board.Claim 对过期租约授予接管、对活租约报 ErrTaken——issue #87 之后的既有语义)。 Recover 不自建第二套时钟判据:它对每个认领态的任务直接尝试 Claim, 存储侧的结论就是结论。这与「判据归存储,不归进程」同一条纪律—— 恢复方拿本地时钟比对 Until,跨进程时钟对不上时会把活任务抢过来, 两个执行者做同一件事。

Package worker Worker Runtime 的**生命周期契约与驱动**:注册 → 心跳 → 领取 → 执行 → 续期/恢复 → 优雅退出。

生命周期: Experimental(v0.35.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。

它补的是哪一段(issue #106)

@delegate@ 是委托的契约面(能不能交 / 交给谁 / 回来算不算完成), @taskboard@ 是认领的契约面(谁负责哪个子任务、怎么把认领还回去)—— 但「执行这些子任务的 worker 自己怎么活」此前没有机制面:各宿主自己写 注册、心跳、领取循环、退出清理,各写一套必然各漏一样(漏心跳 ⇒ 别人 以为它死了;漏续期 ⇒ 长任务必被接管;漏注销 ⇒ 注册表里全是幽灵)。

本包把生命周期收成两样:

  1. @@Registry@@:worker 注册/心跳/注销的**存储中立契约**(与 taskboard.Board 同一范式:语义归本包,落库归宿主);
  2. @@Loop@@:把六段生命周期串起来的**驱动**——领取走 taskboard.Board, 续期走 taskboard.RenewingBoard(issue #87 的能力,心跳不是摆设: 它续的就是那条契约的租约),退出走排水语义。

心跳与续期是两个心跳(都接上了既有契约)

  • **worker 心跳**(@@Registry.Heartbeat@@):「这个 worker 还活着」—— 注册表按它判离线,是资格检查不是纯计时(令牌不匹配即拒绝);
  • **任务租约续期**(@@taskboard.RenewingBoard.Renew@@):「这次认领 还有资格」——它是 issue #87 定的语义:校验令牌仍是最新代 + 推后 到期时刻,**同一次原子操作**。租约易主(@@ErrLeaseLost@@)时驱动 **取消在途执行的 ctx**:资格没了,施加副作用前必须收手——这正是 sideeffect「危险窗口要在施加之前封口」的同一条纪律在 worker 侧的落法。

并发池(issue #196)

Config.Concurrency 缺省 1 = 串行驱动(领一个、跑完、再领下一个),既有 宿主的语义逐字不变。显式 >1 时领取与执行解耦:领取环单点认领,执行体在 有界池里并行,每任务独立 token / cancel / 连续续期失败计数;慢任务不再 占住整个副本的领取能力。停机仍是「停止领取 + 在途逐个收场(WithoutCancel 落库)」,排水上界由 handler 对 ctx 取消的响应决定(与串行同一条契约)。

恢复(Recover)判资格不判时钟

崩溃恢复 = 接管前任留下的过期任务。@@Recover@@ 对每个在认领态的任务 直接尝试 @@Claim@@:租约仍活的被 @@ErrTaken@@ 拒(跳过),已过期的被 存储侧判过资格、授予新代——**过期判定归存储侧**(与 taskboard 的 判据归存储同一条纪律),本包不自建第二套时钟判据。

边界(契约 + 进程内参考实现;跨进程落库归宿主)

本包含契约、驱动与一份**进程内参考实现**(MemRegistry,memory.go): 后者的原子性来自进程内互斥锁,只给契约用例与宿主当形态示范——多副本 共享注册表的跨进程实现(Redis/PG/etcd)归宿主,本仓零数据库依赖。 端到端演示仍在 examples/worker-runtime(Worker 生命周期要靠真实的任务板 与注册表才能验证)。

Index

Constants

View Source
const DefaultPollInterval = 200 * time.Millisecond

DefaultPollInterval 领取轮询的缺省间隔。

Variables

View Source
var ErrInvalidConfig = errors.New("worker: 配置非法")

ErrInvalidConfig Loop/Spec 的配置非法(空 ID、非正 TTL、心跳间隔不短于 注册有效期等)。

装配期就红:心跳间隔长于有效期 = 注册必然周期性过期,症状是 「同事 sees 幽灵/失踪交替」,而配置里每个数字看起来都合法。

View Source
var ErrLeaseUnconfirmed = errors.New("worker: 任务租约无法确认持有资格(连续续期失败跨过 TTL)")

ErrLeaseUnconfirmed 在途任务的租约连续续期失败跨过一个 TTL:驱动无法 确认自己仍是持有者,已取消在途执行并停止领取收刀(issue #179)。

与 @@ErrNotRegistered@@ 分列:那是身份没了,这是任务资格答不出来—— 两者对宿主的处置不同(前者查注册表/顶替,后者查任务板/存储健康)。 驱动报它即已收刀:续不上还继续开工,施加的每个副作用都可能是 与新持有者的双份。

View Source
var ErrNotRegistered = errors.New("worker: 注册已失效(令牌不匹配或有效期已过)")

ErrNotRegistered 注册已失效:令牌不匹配、注册被顶替、或有效期已过。

心跳拿到它 = 这个 worker 的身份已经没了(凭据由注册表铸造,丢了就是 丢了)。驱动收到它即停止领取新任务、收刀退出——身份没了还继续领任务, 账都记不到它头上。

Functions

func Recover

func Recover(ctx context.Context, board taskboard.Board, agent taskboard.AgentID, ttl time.Duration) ([]taskboard.TaskID, error)

Recover 接管任务板上「认领已过期」的任务(崩溃恢复入口)。

语义:

  • 认领态且租约已过期 → Claim 成功(接管,新令牌新代次),计入返回;
  • 认领态且租约仍活 → @@ErrTaken@@(前任还活着),跳过——**不抢活**;
  • 其余状态(open/failed/done)→ 不属于「恢复」的范畴,跳过 (open 任务本来就能被正常领取循环拿走);
  • 竞争性失败(ErrTaken/ErrBlocked/ErrTerminal/ErrNotFound)都是 「这次没轮上」的正常结论,不构成 error;非竞争类错误(任务板 不可用等)原样上抛。

返回本次成功接管的任务 id(调用方据此留痕:哪些任务换了主人)。 agent 是接管者标识;ttl 是接管后新租约的有效期(>0)。

Types

type Config

type Config struct {
	// Agent 任务认领者标识(taskboard.AgentID;注册 Spec.ID 也取它)。
	Agent taskboard.AgentID
	// TTL 认领租约与注册共用的有效期(>0)。共用一个刻度只是本驱动的
	// 缺省口径——要分开调的宿主自己组装即可(机制面不焊死策略)。
	TTL time.Duration
	// PollInterval 领取轮询间隔(0 = DefaultPollInterval)。
	PollInterval time.Duration
	// HeartbeatInterval 心跳/续期周期(0 = TTL/3)。必须短于 TTL,
	// 否则注册周期性过期(装配期拦下,不静默运行)。
	HeartbeatInterval time.Duration
	// Concurrency 同时在途执行的任务上限(0/1 = 串行,既有行为逐字不变;
	// 负值非法,装配期拦下)。>1 时领取与执行解耦:领取环只做认领并投递,
	// 执行体在有界池里并行——单个慢任务不再占住整个副本的领取能力。
	//
	// 租约契约与串行路径相同,只是**按任务独立**:每个在途任务有自己的
	// token / cancel / 连续续期失败计数;ErrLeaseLost 只取消它自己;
	// 连续续期失败跨过阈值(ErrLeaseUnconfirmed)仍按既有契约停止领取
	// 并收刀。停机时停止领取、等待全部在途收场(handler 无视 ctx 取消
	// 时排水同样无上界——既有语义)。
	Concurrency int
	// Pick 可选的挑选钩子:从候选任务里挑一个认领。缺省按 ID 序取第一个
	// 可认领的(确定性——不依赖任务板返回顺序)。优先级/公平性等挑选策略
	// 由宿主在此接线(判据面见 scheduling 包;本驱动不内嵌第二份)。
	Pick func(candidates []taskboard.Task) (taskboard.TaskID, bool)
	// RenewFailMax 在途租约的连续续期失败阈值:连续失败达到它(且外层
	// ctx 未取消)= 无法确认持有资格,驱动取消在途执行的 ctx 并停止
	// 领取收刀(@@ErrLeaseUnconfirmed@@)。0 = 缺省
	// ceil(TTL/HeartbeatInterval)——连续失败跨过一个 TTL 还没续上,租约
	// 按已到期对待(期间接管者随时可能就位);负值非法(装配期拦下)。
	RenewFailMax int
	// OnLeaseLost 在途租约失去资格时的可观测钩子(nil = 不回调)。
	//
	// 三个触发点(见 @@LeaseLostCause@@):续期报 @@taskboard.ErrLeaseLost@@
	// (租约已易主);连续续期失败到阈值(无法确认持有资格);收场动作
	// (Complete/Release)被 @@taskboard.ErrLeaseLost@@ 拒(结果作废)。
	// 三个都是「本次执行的结果已作废」的事实,不是成功路径——宿主据此
	// 计数/留痕/告警,静默吞掉它们下游的非幂等副作用就可能双份(issue
	// #179 的触发序列)。回调在心跳协程/收场路径上同步调用:快返回,
	// 别在里面做重活。
	OnLeaseLost func(task taskboard.TaskID, cause LeaseLostCause)
}

Config 驱动配置(零值不可用;NewLoop 做装配期校验)。

type EffectRunner added in v0.39.0

type EffectRunner interface {
	// ExecuteWith 抢闸 → 准备 → 持有资格检查 → 施加 → 记账(语义见
	// sideeffect.Runner.ExecuteWith)。
	ExecuteWith(ctx context.Context, act sideeffect.Action, eff sideeffect.Effect) (sideeffect.Outcome, sideeffect.Result, error)
	// Reconcile 对账裁决结果未知的 Key(语义见 sideeffect.Runner.Reconcile)。
	Reconcile(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
}

EffectRunner 受管执行器依赖的副作用编排面(*sideeffect.Runner 满足)。

收成接口而不是直接收 *sideeffect.Runner:执行器的用例要能精确构造 「Applied / Replayed / Contended / Uncertain」四种结论,而这两种结论的 真实构造需要完整的存储替身;接口让编排判据与存储实现解耦(生产构造 仍只接受 *sideeffect.Runner 的实现,见 NewManagedExecutor)。

type Handler

type Handler interface {
	Execute(ctx context.Context, task taskboard.Task) error
}

Handler 一个任务的执行体(宿主实现;本包不认识任务内容)。

Execute 收到的 ctx 在「租约易主」「外层停机」时被取消:**施加副作用之前** 应检查它。返回 nil ⇒ 驱动 Complete 任务;返回 err ⇒ 驱动 Release 任务 (任务可被重做)。

type HandlerFunc

type HandlerFunc func(ctx context.Context, task taskboard.Task) error

HandlerFunc 函数适配器。

func (HandlerFunc) Execute

func (f HandlerFunc) Execute(ctx context.Context, task taskboard.Task) error

Execute 实现 Handler。

type LeaseLostCause added in v0.39.0

type LeaseLostCause int

LeaseLostCause 在途租约失去资格的原因(@@Config.OnLeaseLost@@ 的判别面)。

const (
	// LeaseLostTakenOver 续期报 @@taskboard.ErrLeaseLost@@:租约已易主
	//(新持有者在位),在途执行的 ctx 随之取消。
	LeaseLostTakenOver LeaseLostCause = iota
	// LeaseLostUnconfirmed 连续续期失败跨过阈值:无法确认持有资格——
	// 取消在途 ctx 并停止领取(施加之前封口;本次连「谁在持」都答不出)。
	LeaseLostUnconfirmed
	// LeaseLostOnFinalize 收场动作(Complete/Release)被
	// @@taskboard.ErrLeaseLost@@ 拒:任务已归新持有者,本次结果作废。
	LeaseLostOnFinalize
)

func (LeaseLostCause) String added in v0.39.0

func (c LeaseLostCause) String() string

type Loop

type Loop struct {
	// contains filtered or unexported fields
}

Loop 六段生命周期的驱动。Run 之外的可见状态一律经任务板与注册表读取 ——派生状态只有一个真相(板里是什么状态,外面看到的就是什么状态)。

func NewLoop

func NewLoop(board taskboard.RenewingBoard, registry Registry, handler Handler, cfg Config) (*Loop, error)

NewLoop 校验配置并构造驱动。

func (*Loop) Run

func (l *Loop) Run(ctx context.Context) error

Run 跑完整生命周期(阻塞到外层 ctx 取消或身份丢失)。

返回 nil = 优雅退出(在途已收场、注册已注销); 返回 ErrNotRegistered = 身份在途丢失(已尽力注销); 其余错误 = 装配或基础设施故障。

type ManagedConfig added in v0.39.0

type ManagedConfig struct {
	// Agent 任务认领者标识(必填)。
	Agent taskboard.AgentID
	// ClaimTTL 认领租约有效期(必填,>0)。
	//
	// 必须覆盖「一次副作用 + 一次快照提交」的时长:本执行器不替宿主续期
	// (长动作的续期责任在副作用执行体,见 sideeffect.Runner 的注释)。
	ClaimTTL time.Duration
	// Progress 进度提交面(可选;nil = 本执行器不提交进度)。
	Progress Progress
}

ManagedConfig 执行器配置(零值不可用;NewManagedExecutor 做装配期校验)。

type ManagedExecutor added in v0.39.0

type ManagedExecutor struct {
	// contains filtered or unexported fields
}

ManagedExecutor 受管任务执行器(可组合组件;无共享可变状态)。

func NewManagedExecutor added in v0.39.0

func NewManagedExecutor(board taskboard.RenewingBoard, effects EffectRunner, cfg ManagedConfig) (*ManagedExecutor, error)

NewManagedExecutor 装配执行器。

func (*ManagedExecutor) Execute added in v0.39.0

Execute 受管执行一个任务(阻塞到本次收场)。

返回的 Outcome 是**副作用闸的结论**(Applied / Replayed / Contended / Uncertain)——调用方据此区分「我做完了」「别人做过了」「没轮上我」 「上次结果未知」。error 只表示本次调用没能完整走完编排(认领失败、 副作用失败、进度失败、收口被拒);Contended 不带 error(正常判据)。

各结论的处置:

  • Applied / Replayed → 快照提交(若装配)→ Complete;
  • Contended → 释放任务板租约(让别的 worker 试),不 Complete;
  • Uncertain → **不 Complete**、释放租约;副作用闸继续挡着重试;
  • Complete 被 ErrLeaseLost 拒 → 如实返回(任务已归新持有者), **不重试、不覆盖**——本次副作用已记账,重试会与真正持有者重复。

func (*ManagedExecutor) Resolve added in v0.39.0

Resolve 对账裁决「结果未知」的副作用 Key(转发 Runner.Reconcile)。

它不碰任务板:裁决的对象是**副作用的事实**(到底做没做),不是任务归属。 裁决为已生效后,下一次 Execute 拿到 OutcomeReplayed,跳过执行直接收口。

type ManagedWork added in v0.39.0

type ManagedWork struct {
	// Action 副作用动作。Key / Resource 留空时由任务 id 派生
	// (key = "task:" + id,resource = id)——同一次任务的重试因此天然
	// 共用同一个幂等键;宿主需要更细的粒度时显式给。
	Action sideeffect.Action
	// Effect 执行体(Prepare / Apply;Apply 必填)。
	Effect sideeffect.Effect
	// Snapshot 成功后构造进度快照(可选;nil = 不记录进度)。
	//
	// 返回 false 表示「这次任务没有进度可记」(不是错误,也不阻塞 Complete)。
	// 配置了 Snapshot 但没有装配 Progress ⇒ 装配期之外的显式错误,不会
	// 静默跳过(静默跳过会让宿主以为进度落了库)。
	Snapshot func(task taskboard.Task, res sideeffect.Result) (checkpoint.Snapshot, bool, error)
}

ManagedWork 一个受管任务要做的动作(由宿主按任务给出)。

type MemRegistry added in v0.39.0

type MemRegistry struct {
	// contains filtered or unexported fields
}

MemRegistry Registry 的进程内参考实现。经 NewMemRegistry 构造; 零值可用(内部状态惰性初始化)。并发安全。

func NewMemRegistry added in v0.39.0

func NewMemRegistry(opts ...RegistryOption) *MemRegistry

NewMemRegistry 构造参考实现。opts 见 RegistryOption。

func (*MemRegistry) Deregister added in v0.39.0

func (m *MemRegistry) Deregister(_ context.Context, id, token string) error

Deregister 注销(凭令牌;过期的注册仍可凭原令牌收尾)。

func (*MemRegistry) Heartbeat added in v0.39.0

func (m *MemRegistry) Heartbeat(_ context.Context, id, token string, ttl time.Duration) (time.Time, error)

Heartbeat 心跳 = 资格检查 + 延长有效期(同一把锁内完成——原子)。

func (*MemRegistry) List added in v0.39.0

func (m *MemRegistry) List(_ context.Context) ([]Status, error)

List 全量快照(Alive 用注册表自己的时钟判——判据归存储侧)。 过期记录保留并显式 Alive=false(契约允许实现自行清理;这里选择让 幽灵可见:运维看到「有一条过期注册」比「它凭空消失」更容易解释)。

func (*MemRegistry) Register added in v0.39.0

func (m *MemRegistry) Register(_ context.Context, spec Spec) (Registration, error)

Register 注册一个 worker(同 ID 顶替旧注册并铸新令牌)。

type Progress added in v0.39.0

type Progress interface {
	Commit(ctx context.Context, s checkpoint.Snapshot) error
}

Progress 进度快照的提交面(*checkpoint.Committer 满足)。

只收 Commit 一个方法:单调判定(SaveIfNewer + 进程内闸)在 Committer / StoreCAS 里,本执行器不重写。

type Registration

type Registration struct {
	// ID worker 标识。
	ID string
	// Token 注册表铸造的凭据。
	Token string
	// ExpiresAt 当前有效期终点(存储时钟口径;心跳成功后前移)。
	ExpiresAt time.Time
}

Registration 一次注册的凭证(由注册表铸造;心跳与注销的唯一凭据)。

与 taskboard「令牌由存储铸造」同一条纪律:调用方自带的凭据不是凭据 ——凭据铸造在注册表的原子操作里,调用方拿到的只是它。

type Registry

type Registry interface {
	// Register 注册一个 worker(同 ID 顶替旧注册并铸新令牌)。
	Register(ctx context.Context, spec Spec) (Registration, error)
	// Heartbeat 心跳 = 资格检查 + 延长有效期(凭 Token;TTL 语义与
	// Register 一致:正数按存储时钟推算,<=0 报错——「不设限的注册」
	// 会让幽灵永远在线)。
	Heartbeat(ctx context.Context, id, token string, ttl time.Duration) (time.Time, error)
	// Deregister 注销(凭 Token;优雅退出收尾)。
	Deregister(ctx context.Context, id, token string) error
	// List 全量快照(判据归存储侧:Alive 用存储时钟判)。
	List(ctx context.Context) ([]Status, error)
}

Registry worker 注册表的存储中立契约。

实现方必须保证:

  • Register / Heartbeat / Deregister 的**资格校验与写入**是一次原子操作 (心跳推后有效期与校验令牌不可分——拆两步就是「假心跳」: 顶替者已在位,原持有者的心跳延长的却是别人的注册);
  • 心跳凭 Token 认人,不匹配报 @@ErrNotRegistered@@(不静默成功);
  • ExpiresAt 由**存储自己的时钟**推算(调用方时钟与存储时钟不可假设一致)。

type RegistryOption added in v0.39.0

type RegistryOption func(*registryConfig)

RegistryOption MemRegistry 的装配选项。

func WithRegistryClock added in v0.39.0

func WithRegistryClock(now func() time.Time) RegistryOption

WithRegistryClock 注入注册表读时钟的方式(测试与演练用)。

生产装配不必注入:到期判定走注册表自己的时钟是契约要求, 多副本下这个「自己的时钟」应当是存储侧时钟(见 Registry 的说明)。

type Spec

type Spec struct {
	// ID worker 标识(宿主词表;空串非法)。允许重复注册:后到者顶替
	// 先到者并铸新令牌(崩溃重启是正常路径,先到者的心跳从此被拒
	// ——它由此得知自己已被顶替,而不是靠幽灵状态猜)。
	ID string
	// Labels 原样携带的标签(能力声明、分组等;语义由宿主解释)。
	Labels map[string]string
	// TTL 注册有效期(>0 必填):两次心跳之间隔多久算离线。
	// 这与任务的租约 TTL 是两回事——worker 活着不等于某个任务还在做。
	TTL time.Duration
}

Spec 注册声明:worker 是谁、要多久的心跳周期。

func (Spec) Validate

func (s Spec) Validate() error

Validate 装配期自检(违者报 ErrInvalidConfig)。

type Status

type Status struct {
	// ID worker 标识。
	ID string
	// Labels 注册时声明的标签(快照)。
	Labels map[string]string
	// ExpiresAt 有效期终点(存储时钟口径)。
	ExpiresAt time.Time
	// Alive 注册表判定:有效期未过(在线)。已过期的记录是否被清除
	// 由实现决定(清了就不在 List 里;不清则 Alive=false 显式可见)。
	Alive bool
}

Status 注册表里一条 worker 记录的快照(List 的产出)。

Alive 由**注册表用自己的时钟**判(判据归存储侧,不归调用方—— 跨进程时钟对不上,调用方拿 time.Now 比对 ExpiresAt 是自建第二套判据)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL