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」—— 失败即回板,可被重做。这条默认语义作用在**不可幂等**动作上就是重复施加: 下单、发信、改远程状态这类动作重跑一次,副作用就双份。
本执行器把「执行意图与对账」强制接进任务生命周期,四步不能重排、不能漏:
- **Claim**:拿租约与令牌(令牌由任务板铸造——任务归属的唯一凭据);
- **SideEffect.Execute**:走 @@sideeffect.Runner@@ 的既有契约—— Acquire 原子登记执行意图 + 栅栏令牌,施加前做持有资格检查, 失败按 @@RetrySafety@@ 分流出「可重试」与「结果未知」;
- **Checkpoint**:副作用记账成功后单调提交进度快照(不覆盖更高版本);
- **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 自己怎么活」此前没有机制面:各宿主自己写 注册、心跳、领取循环、退出清理,各写一套必然各漏一样(漏心跳 ⇒ 别人 以为它死了;漏续期 ⇒ 长任务必被接管;漏注销 ⇒ 注册表里全是幽灵)。
本包把生命周期收成两样:
- @@Registry@@:worker 注册/心跳/注销的**存储中立契约**(与 taskboard.Board 同一范式:语义归本包,落库归宿主);
- @@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
- Variables
- func Recover(ctx context.Context, board taskboard.Board, agent taskboard.AgentID, ...) ([]taskboard.TaskID, error)
- type Config
- type EffectRunner
- type Handler
- type HandlerFunc
- type LeaseLostCause
- type Loop
- type ManagedConfig
- type ManagedExecutor
- type ManagedWork
- type MemRegistry
- func (m *MemRegistry) Deregister(_ context.Context, id, token string) error
- func (m *MemRegistry) Heartbeat(_ context.Context, id, token string, ttl time.Duration) (time.Time, error)
- func (m *MemRegistry) List(_ context.Context) ([]Status, error)
- func (m *MemRegistry) Register(_ context.Context, spec Spec) (Registration, error)
- type Progress
- type Registration
- type Registry
- type RegistryOption
- type Spec
- type Status
Constants ¶
const DefaultPollInterval = 200 * time.Millisecond
DefaultPollInterval 领取轮询的缺省间隔。
Variables ¶
var ErrInvalidConfig = errors.New("worker: 配置非法")
ErrInvalidConfig Loop/Spec 的配置非法(空 ID、非正 TTL、心跳间隔不短于 注册有效期等)。
装配期就红:心跳间隔长于有效期 = 注册必然周期性过期,症状是 「同事 sees 幽灵/失踪交替」,而配置里每个数字看起来都合法。
var ErrLeaseUnconfirmed = errors.New("worker: 任务租约无法确认持有资格(连续续期失败跨过 TTL)")
ErrLeaseUnconfirmed 在途任务的租约连续续期失败跨过一个 TTL:驱动无法 确认自己仍是持有者,已取消在途执行并停止领取收刀(issue #179)。
与 @@ErrNotRegistered@@ 分列:那是身份没了,这是任务资格答不出来—— 两者对宿主的处置不同(前者查注册表/顶替,后者查任务板/存储健康)。 驱动报它即已收刀:续不上还继续开工,施加的每个副作用都可能是 与新持有者的双份。
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 ¶
Handler 一个任务的执行体(宿主实现;本包不认识任务内容)。
Execute 收到的 ctx 在「租约易主」「外层停机」时被取消:**施加副作用之前** 应检查它。返回 nil ⇒ 驱动 Complete 任务;返回 err ⇒ 驱动 Release 任务 (任务可被重做)。
type HandlerFunc ¶
HandlerFunc 函数适配器。
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 之外的可见状态一律经任务板与注册表读取 ——派生状态只有一个真相(板里是什么状态,外面看到的就是什么状态)。
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
func (e *ManagedExecutor) Execute(ctx context.Context, id taskboard.TaskID, work ManagedWork) (sideeffect.Outcome, error)
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
func (e *ManagedExecutor) Resolve(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
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 是谁、要多久的心跳周期。
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 是自建第二套判据)。