Documentation
¶
Overview ¶
check.go —— 快照不变量的**判据面**(issue #195 起按租户身份判定)。
身份是 (Tenant, ID):同一 ID 在不同租户下是两条任务;依赖只在同租户内 解析(跨租户引用按不存在处理——租户之间本来就不可见)。空租户 = 默认 命名空间,此时身份退化为 ID,判定与旧版逐字一致。
contention.go —— 认领的并发正确性**判据**(判据,不是测试风格)。
生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。
为什么判据要长在包里而不是只在测试里 ¶
「并发认领同一任务只能有一个赢家」是 @@Board@@ 的**契约条款**,不是某个 实现的性质。写在测试里 → 每个宿主各写一份、各判一套;写成导出的判据 → 宿主的存储实现只要被这个函数跑一遍就算验过契约(@sidetest@ 的同一范式)。
判据怎么判 ¶
让 N 个 agent 在同一个起跑线上同时 @@Claim@@ 同一个任务:
- 成功者必须**恰好 1 个**(0 个说明谁都认领不了;>1 个说明存储没做到原子);
- 失败者的错误必须是 @@ErrTaken@@(不能是 ErrBlocked / ErrTerminal 之类—— 那说明这些 agent 压根没走到争用那一步,这次判定没测到想测的东西);
- 任何**其它**错误都是基础设施故障(要显式报出来,不能混进「输家」里)。
第三条容易被忘掉:把「数据库连不上」也算成「输家」,判据就会在存储坏掉时 **变绿**——它测到的是「没有人赢」而不是「只有一个赢家」,而两者都符合 「winners <= 1」。
第二条判据:重复令牌(issue #97) ¶
@@DuplicateTokenSubmit@ 让多个 worker 同时用**同一个**令牌提交,成功者 必须**恰好 1 个**——它撞的是「校验与写入分离」这一形态:各拿各的令牌的 并发认领(@@ConcurrentClaim@@)撞不出它,必须让同一令牌的使用者正面相撞。
ready.go —— 批量领取的可选契约(issue #189)。
它补的是哪一段 ¶
Board.Claim 一次只认领一个任务;worker.Loop 的缺省路径是「每拍 List 全量 → 本地挑一个 → Claim」。单副本时这不是问题,多副本时列表量随队伍线性 放大:N 个 worker 每 200ms 各拉一次全量任务,即使一个都没得领。
ReadyBoard 把「挑就绪候选」这一步挪到存储侧:存储按自己的就绪索引 (open/failed + 依赖完成 + 未被活着占用)一次领取 n 个,调用方不再需要 全量 List。它是**可选**接口——不实现它的 Board 保持原有单条 Claim 路径, 语义与默认行为一字不改(本仓的默认路径零回归纪律)。
与 Board.Claim 的关系 ¶
批量领取不是第二套状态机:每一笔认领仍然走 Claim 的全部判据(原子 读-判-写、令牌由存储铸造、代次严格递增、过期租约可接管、依赖完成才 可认领)。实现可以在一次事务里提交整批,也可以逐笔调用 Claim;契约只 判结果:
- 返回的每个任务都是**本次**认领成功的(令牌与代次由存储铸造);
- 同一批里任务 id 不重复;
- 并发调用之间同一任务至多归一个调用方(原子性仍由存储保证);
- 数量至多 n;就绪任务不足 n 时返回实际领到的,不报错(「没那么多活」 是正常结论,不是故障)。
单条 Claim 保持默认 ¶
本接口不改 Board,也不强制实现。worker.Loop 的缺省领取路径仍走 List + Claim;要启用批量领取的宿主把 Board 构造成 ReadyBoard 并自行 接线(或在 Loop 之外驱动)。这样「未实现批量领取」的存储不会被新契约 拖红,已实现的存储可以在自己的量级上做索引优化。
renew.go —— 租约续期与接管代次的契约(issue #87)。
它补的是哪一段 ¶
长任务必然撞上租约到期:执行时长超过 Until 而没有续期手段,宿主只能在 「估一个很大的租约」与「永久占用」之间二选一——估大了,持有者崩了之后 任务要白等很久才被接管;估小了,活还没干完闸就没了。
更要害的是接管后的世界:旧持有者(GC 停顿、网络分区后恢复)迟到的提交, 此前只能靠「新旧令牌恰好不同」保安全——那是碰巧,不是判据。
Renew 不是心跳,是资格检查 ¶
它同时做两件事,缺一不可:
- 把到期时刻推后(长动作不至于中途失去闸);
- 校验令牌仍是该任务的最新一代——不是则拒绝,**不做任何修改**。
只做第 1 条的续期是**假续期**:租约已被接管时,延长的其实是**别人的闸**, 持有者却以为延长的是自己的,于是两份闸同时开着,同一份工作被做两遍。
接管代次(Fence)与令牌同源 ¶
代次与令牌在同一次 Claim 的同一次原子操作里铸造,同一任务上**严格递增** (Renew 不递增——续期不是接管)。它给两样东西:
- 判据:接管后的新代必须大于旧代(boardtest 的「接管代次严格递增」钉住, 代次不递增的实现必红);
- 栅栏:宿主的下游资源可凭「代次比已见过的最大值小」拒收过期持有者的 迟到写入(与 sideeffect.FencedSink 同一形态、同一纪律)。
旧持有者迟到的提交不需要专门的判别机制:令牌不匹配即 @@ErrLeaseLost@@。 接管必然铸造新令牌,故迟到提交**必然**被拒,且不波及新持有者。
state.go —— 任务状态的导出枚举面。
为什么必须可枚举 ¶
词表是**判定依据**:宿主接任务板协议时要知道任务有哪些合法状态。此前 这张词表是包私有且没有任何枚举出口,宿主只能手抄一份常量清单——内核新增 一个取值,宿主那份不会跟着变,且没有任何判据会红(「三份手抄表 = 三份会 漂的真相」,issue #356)。
本文件的出口**直接读判定用的同一张私有 map**,不另写列表:枚举与判定 同源,新增取值只需改一处。返回的切片是**新分配的副本**(排序后),宿主 改写它不影响判定面。
与 Valid 的关系 ¶
枚举回答「全部合法值」,谓词回答「这个值是否合法」。两者必须逐字一致: 枚举里的每个值都过谓词;谓词为真的每个值都在枚举里。用例做双向断言 (单向断言会漏掉「词表里有但没导出」)。
Package taskboard 多 agent 协调面的**存储中立契约 + 一致性判据**。
它补的是哪一段 ¶
@dispatch@ 只回答「能不能派」。派出去之后的三件事——谁负责哪个子任务、 它依赖谁、怎么把认领还回去——此前**没有任何机制面**:各宿主自己拿一张 表或一个 map 兜着,于是「同一个子任务被两个 agent 同时认领」这种错在 报告里读起来完全正常(两条分支都干完了活,各自都以为自己是负责人)。
本仓给什么、不给什么 ¶
**给**:① 存储中立的接口(@@Board@@);② 快照的**不变量判据**(@@Check@@, 纯函数,宿主可以随时拿当前快照跑一遍);③ 并发正确性的**可跑断言** (@@ConcurrentClaim@@,判据本身而不是测试风格);④ 可选的**批量领取面** (@@ReadyBoard@@.ClaimReady,issue #189:存储侧一次领取至多 n 个就绪 任务,单条 Claim 保持默认与语义不变)。
**不给**:存储实现。表结构、事务边界、持久化形态是宿主资产——本仓给一份 参考实现,宿主就会照着改它,最后两份真相并存。这与 @checkpoint.StoreCAS@ 的分工完全同构:契约与判据归内核,落库归宿主。
为什么「认领」必须是原子的 ¶
认领是**读-判-写**:读当前状态、判依赖是否完成、写 owner。三段分开做, 两个 agent 会读到同一个「open」,各自判定自己可以认领,然后先后写入—— 两个赢家。这与 @@commitgate@@ 的「两条并行分支都赢了」是同一种失效, 而这里的代价更直接:同一份工作被做两遍,或者两份互相覆盖的结果被当成一份。
故契约要求 @@Board.Claim@@ **由存储实现保证原子性**,本包只判结果 (并发跑 N 次,成功者必须恰好 1 个)。
释放认领凭令牌,不凭内容 ¶
与 @@commitgate@@ 的教训同源:用「任务 id + agent 名」认人判的是 「内容相同」,不是「同一次占用」。同名 agent(并行分支常同名)或 「失败 → 释放 → 重试」这条推荐路径都会撞上,于是输家放掉赢家的闸、 上一轮的迟到释放放掉新一轮的闸。故 @Lease@ 里的 token 由存储**铸造**, @@Release@@ / @@Complete@@ 只认 token。
令牌必须由存储铸造(v0.33.0 起) ¶
此前 @Claim@ 收的是调用方自带的 @Lease@(含 token)——契约写着 「token 由存储铸造」,实现却让调用方造 token。两者对不上时,**实现赢**: 调用方能造出任意 token,于是「输家的迟到释放放掉赢家的闸」这条失效形态 又回来了,而报告里一切正常。
故 @Claim@ 改收 @ClaimRequest@(只说「要多长的租约」),token 由存储铸造 并随返回的 @@Task@ 给出。契约与实现从此一致,且不可能被调用方绕过。
续期与接管代次(v0.33.0 起,详见 renew.go) ¶
长任务没有续期手段就必然被接管;续期走 @@RenewingBoard.Renew@@—— 它是**资格检查**不是心跳:校验令牌仍是最新代,同时把到期时刻推后。 接管代次 @@Fence@@ 与令牌**同源**(同一次认领的同一原子操作铸造), 同一任务上严格递增;旧持有者迟到的提交凭「令牌不匹配 ⇒ @@ErrLeaseLost@@」 必然被拒,且不波及新持有者。
多租户(issue #195) ¶
任务身份是 @@(Tenant, ID)@@:同一 ID 在不同租户下是两条互不相干的任务。 @@Task.Tenant@@ 是开放键(内核不解释语义);**空租户 = 默认/单租户命名 空间**,此时身份退化为 ID,旧行为逐字不变。
支持租户的实现必须同时满足以下条款(单租户实现保持空租户即可,不受影响):
- **键由实现按租户作用域生成**,调用方不把租户拼进 TaskID——调用方 自由拼键时,租户段与 id 段的分界就成了第二个约定,撞键是必然;
- 租户上下文经 ctx 传递(见 tenant 包的传递契约)——它仍是机制间的 唯一通道:不另设全局变量、不把租户挂到 Board 结构体上;
- 作用域内 @@List@@ 不含他租户任务;@@Claim@@ / @@Release@@ / @@Complete@@ / @@Renew@@ 对他租户任务一律 @@ErrNotFound@@(不可见 = 不存在,不泄露存在性)——跨租户领取与收场必须被拒;
- 实现声明「本板必须带租户上下文」时,缺租户 fail-closed (@@tenant.ErrNoContext@@),与写路径入口同一口径;空租户与缺租户 不是一回事:前者是默认命名空间,后者是拒绝。
@@Check@@ 接受混合租户快照:按 (Tenant, ID) 判重,依赖只在同租户内解析 (跨租户依赖按不存在处理——租户之间本来就不可见)。详见 check.go。
Index ¶
- Constants
- Variables
- func ConcurrentClaim(ctx context.Context, b Board, id TaskID, agents []AgentID, ttl time.Duration) (int, error)
- func DuplicateTokenSubmit(ctx context.Context, b Board, id TaskID, workers int, ttl time.Duration) (int, error)
- func LeaseHeld(t Task, now time.Time) bool
- type AgentID
- type BatchRenewingBoard
- type Board
- type ClaimRequest
- type Fence
- type Lease
- type Problem
- type ReadyBoard
- type RenewRequest
- type Renewal
- type RenewingBoard
- type State
- type Task
- type TaskID
Constants ¶
const ( CodeEmptyID = "empty_id" CodeDuplicateID = "duplicate_id" CodeUnknownState = "unknown_state" CodeUnknownDep = "unknown_dep" CodeSelfDep = "self_dep" CodeCycle = "dep_cycle" CodeClaimedNoLease = "claimed_without_lease" CodeLeaseNoClaim = "lease_without_claim" CodeBlockedClaim = "blocked_claim" CodeTerminalClaimed = "terminal_claimed" )
不变量类别。
Variables ¶
var ( // ErrNotFound 任务不存在。 ErrNotFound = errors.New("taskboard: 任务不存在") // ErrTaken 任务被他人活着持有。 ErrTaken = errors.New("taskboard: 任务已被他人认领") // ErrBlocked 依赖未完成。 ErrBlocked = errors.New("taskboard: 依赖未完成") // ErrTerminal 任务已是终态。 ErrTerminal = errors.New("taskboard: 任务已是终态") // ErrUnknownState 任务状态不在内核词表内(读不懂 ⇒ 写路径拒绝,不认领)。 // // 与 Check 的 CodeUnknownState 同一事实、同一方向:体检说「这状态非法」, // 认领也必须拒绝——否则一条脏状态行会让副作用照常施加。 ErrUnknownState = errors.New("taskboard: 任务状态不在词表内") // ErrLeaseLost 令牌不匹配(租约已易主或被释放过)。 // // 旧持有者迟到的一切动作——Release / Complete / Renew——都用它拒收: // 接管必然铸造新令牌,令牌不匹配即说明你不是现任持有者。 ErrLeaseLost = errors.New("taskboard: 租约已易主") )
错误哨兵(宿主实现必须复用,不要各造一套:判定方按 As/Is 认人)。
var ErrInvalidBatch = errors.New("taskboard: 批量领取数量必须为正")
ErrInvalidBatch 批量领取的数量非法(n <= 0)。
零或负数的批量请求无从解释:零个任务等于什么都没做,负数不是数量。 装配/调用方错误要显式拒绝,不静默返回空列表(那会让「配置写错」看起来 像「暂时没有活」)。
Functions ¶
func ConcurrentClaim ¶
func ConcurrentClaim(ctx context.Context, b Board, id TaskID, agents []AgentID, ttl time.Duration) (int, error)
ConcurrentClaim 让多个 agent 同时认领同一个任务,返回成功者数量。
ttl 是本次认领申请的租约有效期(每个 agent 申请同一把长度)—— **令牌由存储铸造**(见 Board.Claim),本判据不碰令牌。
返回的 error 只表示**基础设施故障或契约违反**,不表示「有人输」—— 输家是正常结果。
func DuplicateTokenSubmit ¶ added in v0.34.0
func DuplicateTokenSubmit(ctx context.Context, b Board, id TaskID, workers int, ttl time.Duration) (int, error)
DuplicateTokenSubmit 让多个 worker 同时用**同一个**令牌提交同一任务, 返回成功者数量(必须恰好 1)。
它补的是哪一面(issue #97) ¶
「释放/完成只认 token」这条契约有一个并发缺口:若存储把 Complete 的 **校验**与**写入**拆成两步(先查「claimed 且 token 匹配」、再写 done, 中间没有事务),两个同时用同一令牌的提交者会**都**通过校验、先后写入 ——两个都成功,等于「只认 token」名存实亡。4 个 agent 各拿各的令牌 撞不出这个形态;必须让**同一令牌**的并发使用者正面相撞。
判据怎么判 ¶
本判据自己先认领一次(令牌由存储铸造),再让 workers 个提交者**同时** 用该令牌调 Complete:
- 成功者必须**恰好 1 个**(>1 说明校验与写入没有原子性;0 说明连真持有者 都被拒了,契约同样破);
- 其余必须是 @@ErrLeaseLost@@(正常输家);任何**其它**错误按基础设施故障 显式报出,不混进「输家」里——把存储故障算成输家,判据会在存储坏掉时 变绿。
返回的 error 只表示**基础设施故障或判据无法给出结论**,不表示「有人输」。
func LeaseHeld ¶ added in v0.43.0
LeaseHeld 报告任务当前是否仍被**活持有**(issue #335 的单点判据)。
判定 = 认领态 **且** 租约未过期(Until 零值 = 不限期,按在持判——当成 已过期会让「两个执行者同时认领」变成「两个赢家」)。
为什么收敛成导出函数:此前 coord / examples 的两个参考实现 / controlplane 各写一份等价判据,而 controlplane.MemStore.Claim **压根没判过期**—— 持有者进程崩掉后任务被永久占用,与 Board.Claim 的「被别人**活着**持有」 契约方向相反。存储实现的 Claim 必须调用本函数,不得各写一份(第二份 判据必然漂移)。
Types ¶
type BatchRenewingBoard ¶ added in v0.43.0
type BatchRenewingBoard interface {
RenewingBoard
// RenewBatch 一次存储往返续期多条(契约见类型级说明)。
RenewBatch(ctx context.Context, reqs []RenewRequest) ([]Renewal, error)
}
BatchRenewingBoard 可选的**批量续期面**(issue #266)。
接缝契约(issue #369) ¶
@seam: no-reentry no-blocking panic-isolated
与前一条同口径:不得重入同一任务板路径、不得阻塞心跳节拍;实现 panic 由 worker 的 renewBatchCall recover + async.ReportPanic 隔离,整批按基础设施 失败处理(逐条结果不可信),心跳协程继续运行(issue #368)。
为什么单独成接口:不是每份存储都能一次原子地续多条;判定方按类型断言 认人,缺失时退回逐条 + 有界并发。实现方必须保证:
- **逐条独立判定**:单条令牌错误/过期只让该条 ErrLeaseLost,不影响 其它条目的续期(返回顶层的 error 只表示**整批**基础设施失败—— 此时逐条结果不可信,调用方按整批失败处理);
- 返回切片与请求**同序、等长**,每条结果的 ID 回显请求 ID;
- 批量不改变 Renew 的语义:续期不递增 Fence、不换 Token;每条仍按 存储自己的时钟校验与推算到期时刻。
type Board ¶
type Board interface {
// List 返回当前全部任务的快照(顺序不要求,判据会排序)。
List(ctx context.Context) ([]Task, error)
// Claim 认领一个任务。
//
// **令牌由存储铸造**并随返回的 Task 一起给出(Task.Lease.Token 与
// Task.Lease.Fence 同一次原子操作铸造,Fence 在同一任务上严格递增);
// 调用方只给「要多长的租约」(ClaimRequest),不给令牌。
//
// 以下情形必须报错而不是「尽力而为」:不存在(ErrNotFound)/
// 被别人活着持有(ErrTaken)/ 依赖未完成(ErrBlocked)/ 已是终态
// (ErrTerminal)/ 状态不在词表内(ErrUnknownState)。
//
// ErrUnknownState 是**契约义务**,不是某个实现的可选加固:内核读不懂
// 的状态不得被认领(读不懂 ⇒ 写路径拒绝),否则一条脏状态行会让副作用
// 照常施加。实现应调用 taskboard.State.Claimable 取这份判据,不要各写
// 一份(issue #360)。
Claim(ctx context.Context, id TaskID, agent AgentID, req ClaimRequest) (Task, error)
// Release 归还认领(凭 token)。
Release(ctx context.Context, id TaskID, token string) error
// Complete 标记完成(凭 token)。
Complete(ctx context.Context, id TaskID, token string) error
}
Board 协调面的存储中立契约。
实现方必须保证:
- @@Claim@@ **原子**:读-判-写不可分割(并发认领同一任务只能有一个赢家);
- @@Release@@ / @@Complete@@ **只认 token**,且 token 不匹配时报 @@ErrLeaseLost@@(不许静默成功——静默成功会让输家以为自己的释放生效了);
- @@List@@ 返回**一致快照**(不是边改边读的流);
- @@List@@ / @@Claim@@ 返回的 @@Task@@ **不得与实现内部共享 Deps 的 底层数组**(与 checkpoint.Snapshot.Clone 同款拷贝义务):Task 含 切片字段,按值返回只复制切片头,宿主照契约字面实现时改写返回值元素 会改穿存储内部的任务拓扑。实现可用 @@Task.Clone()@@ 收口这一义务。
支持多租户的实现还必须满足租户条款(见包文档「多租户」):键按 ctx 的 租户作用域生成;他租户任务不可见、不可领、不可收场(一律 ErrNotFound); 声明「必须带租户」时缺租户 fail-closed(tenant.ErrNoContext)。空租户与 缺租户不是一回事:前者是默认命名空间(旧布局),后者是拒绝。
type ClaimRequest ¶ added in v0.33.0
type ClaimRequest struct {
// TTL 本次认领的租约有效期。
//
// 正数 ⇒ 存储按「自己的当前时刻 + TTL」算出到期时刻。
// 零值 ⇒ 不限期(到期时刻为零值,由宿主自担)——持有着崩了会留下一把
// 永久占用,故宿主通常应给一个正的 TTL。
TTL time.Duration
}
ClaimRequest 认领请求:调用方给出**想要多长的租约**,不给出令牌。
为什么请求里没有令牌 ¶
令牌必须由**存储**铸造。调用方自带令牌时,「释放/完成只认 token」 这条契约就名存实亡:调用方能造出任意 token,于是 「同名 agent 的输家迟到释放放掉赢家的闸」这条失效形态又回来了 (commitgate 同源教训:凭令牌释放、不认内容)。
为什么给的是「多长」而不是「到什么时候」 ¶
到期时刻归存储算:调用方的时钟与存储的时钟可能对不上,跨进程时更不能 假设一致。给 TTL,存储按**自己的**当前时刻推算,两边不会各算一套。
type Fence ¶ added in v0.34.0
type Fence uint64
Fence 接管代次(栅栏令牌):同一任务上**每次认领成功**都严格递增。
与 @@Lease.Token@@ **同源**:同一次认领的同一次原子操作里由存储铸造。 Renew **不**递增它——续期不是接管,代次只回答「这是第几任持有者」。
首次认领的取值不限(从 0 或 1 起都可以),契约只要求同一任务上 **严格递增**:新代必须大于旧代。
用途:
- 判据:接管后的代次必须递增(boardtest 的「接管代次严格递增」钉住, 代次不递增的实现必红);
- 栅栏:宿主的下游资源可凭「代次比已见过的最大值小」拒收过期持有者的 迟到写入——与 sideeffect.FencedSink 同一形态、同一纪律 (比较与写入须在下游的同一次原子操作里完成)。
type Lease ¶
type Lease struct {
// Token 由存储**铸造**的唯一令牌(释放与完成的唯一凭据)。
//
// 它**不由调用方提供**——见 ClaimRequest 的注释:调用方能造令牌,
// 「凭令牌认人」就名存实亡。
Token string
// Fence 接管代次(栅栏令牌):与 Token **同一次原子操作**铸造,同一任务上
// 每次认领成功严格递增;续期**不**递增(续期不是接管)。
//
// 判据与下游栅栏的用法见 Fence 与 RenewingBoard 的契约说明(renew.go)。
Fence Fence
// Until 租约到期时刻(零值 = 不限期,由宿主自担)。
//
// 到期后其他 agent 可以接管:进程崩掉时没有它会留下一把永久占用。
Until time.Time
}
Lease 一次认领的凭证。
type Problem ¶
type Problem struct {
// Tenant 相关任务的租户(空 = 默认/单租户命名空间)。
Tenant string `json:",omitempty"`
// Task 相关任务 id。
Task TaskID
// Code 机器可判的类别(宿主按它分流与留痕)。
Code string
// Text 人读的说明。
Text string
}
Problem 一条快照不变量违反。
type ReadyBoard ¶ added in v0.39.0
type ReadyBoard interface {
Board
// ClaimReady 批量领取至多 n 个就绪任务给 agent。
//
// n <= 0 ⇒ ErrInvalidBatch。req 的 TTL 语义与 Board.Claim 完全一致
// (正数按存储时钟推算,零值不限期由宿主自担)。
ClaimReady(ctx context.Context, agent AgentID, n int, req ClaimRequest) ([]Task, error)
}
ReadyBoard 可选的批量领取面(存储侧按就绪索引领取)。
实现方必须保证(与 Board.Claim 同一套判据,不另造一套):
- 返回的任务全部是本次认领成功的,令牌与代次由存储铸造;
- 同一批内任务 id 不重复;并发调用之间同一任务至多一个赢家;
- 只返回**就绪**任务:状态为 open 或 failed(可重做),依赖全部完成; 被活着持有的任务不得返回;过期租约可以按 Claim 的接管语义领取 (返回的令牌是新铸的,旧持有者的迟到提交凭 ErrLeaseLost 被拒);
- 数量至多 n;就绪任务不足时返回实际领到的(可以为空),不报 ErrBlocked / ErrTaken——那些是「这一笔没轮上」,不是批量领取失败。
单个候选的竞争性拒绝(ErrTaken / ErrBlocked / ErrTerminal / ErrNotFound) 会被实现跳过并继续尝试下一个候选;基础设施故障则应中止并返回错误。 **已返回的任务仍然归调用方**(调用方必须按持有者收场),错误只表示 本轮批量没有取满 n 个。
type RenewRequest ¶ added in v0.43.0
type RenewRequest struct {
// ID 任务标识。
ID TaskID
// Token 当前租约令牌(存储校验持有资格)。
Token string
// TTL 续期后的有效期(语义同 ClaimRequest.TTL,按存储时钟推算)。
TTL time.Duration
}
RenewRequest 一条批量续期请求(id + 令牌 + TTL)。
type Renewal ¶ added in v0.43.0
type Renewal struct {
// ID 对应请求的任务标识。
ID TaskID
// Task 续期成功后的任务快照(失败时零值)。
Task Task
// Err 该条续期的判据结果(ErrLeaseLost 等;成功为 nil)。
Err error
}
Renewal 一条批量续期结果(与 RenewRequest 同序一一对应)。
type RenewingBoard ¶ added in v0.34.0
type RenewingBoard interface {
Board
// Renew 续期并确认持有资格(契约见类型级说明)。
Renew(ctx context.Context, id TaskID, token string, req ClaimRequest) (Task, error)
}
RenewingBoard 支持租约续期的 Board。
接缝契约(issue #369) ¶
@seam: no-reentry no-blocking panic-isolated
实现方(宿主存储)必须遵守:
- **不得重入**:Renew 实现内不得回调内核的同一任务板路径 (Claim/Complete/Release/RenewBatch);同一把存储锁不可重入。
- **不得阻塞**:Renew 位于心跳节拍上,必须尽快返回;慢 I/O 会拖住同拍 其它任务的续期(批量面请用 RenewBatch 把往返压成一次)。
- **panic 已隔离**:worker 的续期路径 recover 并上报(并发路径经 async.GoSafe,批量路径经 renewBatchCall),宿主 panic 不会掀翻心跳 协程;本次按一次续期失败计数(issue #368)。
为什么是单独的接口而不是并进 Board ¶
续期要求存储提供「校验持有资格 + 延长到期时刻」的**原子**操作——不是每份 既有实现都具备。并进 Board 等于让全部实现同时破;单独成接口则由判定方按 类型断言认人:**接入 boardtest 套件的实现必须实现它**(套件对缺失硬失败, 不跳过——跳过等于把「没测过」伪装成「通过」)。
Renew 的契约(存储侧必须全部保证) ¶
Renew 续期并**同时确认持有资格**,语义是「我还持有吗,顺便把有效期推后」:
- token 不是该任务当前租约的令牌 ⇒ @@ErrLeaseLost@@,**不做任何修改**。 不许静默成功:过期持有者的迟到续期延长的是**别人的闸**;
- 租约**已过期** ⇒ @@ErrLeaseLost@@。资格在到期时刻终止——过期后任务随时 可能被接管,存储不能既承诺「过期随时可接管」又给死者续命。想继续做, 重新 Claim:要么拿到新租约(新令牌新代次),要么明确得到 @@ErrTaken@@, 不会拿着旧身份悄悄续命;
- 资格校验与延长在**同一次原子操作**里完成(否则「校验通过」与「续期 生效」之间仍有窗口,接管者与续期者可以同时得手);
- TTL 语义与 Claim **完全一致**:正数 ⇒ 按存储**自己的**当前时刻推算新的 到期时刻;零值 ⇒ 不限期(到期时刻清零,宿主自担);
- 续期**不**递增 @@Fence@@、**不**更换 token(不是接管),返回的 Task.Seq 应前进(Until 变了,这是一次任务变更)。
宿主应在**施加副作用之前**调 Renew:返回 @@ErrLeaseLost@@ 说明任务已易主, 本次动作必须放弃——继续做就是与新持有者重复施加。
type State ¶
type State string
State 任务状态。
func AllStates ¶ added in v0.43.0
func AllStates() []State
AllStates 返回任务状态词表的全集(排序后的**新切片**)。
宿主据此渲染任务状态选择器 / 校验落库值,不必手抄常量清单。
注意 done 与 failed 的**词表成员身份**与**终态身份**是两件事:failed 在 词表内但非终态(可重新认领,见 State.Terminal),枚举出口给的是词表成员 集合,不是终态集合。
func (State) Claimable ¶ added in v0.43.0
Claimable 报告该状态是否**可被认领**,返回契约规定的哨兵:
- 词表外 → ErrUnknownState(读不懂 ⇒ 写路径拒绝,不认领);
- 终态(done)→ ErrTerminal;
- 其余(open / claimed / failed)→ nil。
为什么把判定收成一个导出函数(issue #360) ¶
#323 的修法落在 coord.BoardAdapter 一个实现里,契约文本与另外三个参考 实现都没跟上(controlplane.MemStore、examples/pgstore、examples/reference-runtime)。 判据一旦各写一份,第二份必然漂移——本条把「状态能不能领」收成单点:
Valid() 区分「读不懂」与「可再领」;Terminal() 负责终态; Claimable() 把两者折成调用方需要的那个哨兵。
存储实现的 Claim 必须调用本函数(AST 判据见 claim_gate_test.go), 不得只判 Terminal():未知状态不是终态,只看终态会让脏状态行照常领到租约。
func (State) Terminal ¶
Terminal 报告该状态是否**不可再被认领**。
只有 done 是终态:failed 的任务必须能重做,否则一次失败就把子任务永久钉死, 而宿主的补救路径(重新派一个人)会静默失效。
**failed 在词表上非终态,这是刻意的**(见 StateFailed 的常量注释,issue #375): 常量注释曾写「终态」,与本函数相反;两处现在逐字对齐。体检面同样按本函数 判:failed + 残留 owner 不报 CodeTerminalClaimed,failed 也不算「依赖已完成」。
func (State) Valid ¶ added in v0.43.0
Valid 报告状态是否在内核词表内。
为什么必须导出(issue #323) ¶
词表外状态代表「内核读不懂这个状态」:体检面(Check)会报 CodeUnknownState,但写路径此前只判 Terminal()(未知状态不是终态)⇒ 同一个状态「体检说非法、Claim 说可领」。宿主需要能自己区分 「状态合法且非终态」与「状态不在词表内」——Valid() 就是这个判据。
Terminal() 对词表外状态仍返回 false(不能把「读不懂」说成「终态」), 所以写路径必须显式消费 Valid()(或 Claimable()),不能靠 Terminal() 反推。 接口契约已把 ErrUnknownState 列为 Claim 的必报错(issue #360)。
type Task ¶
type Task struct {
// Tenant 租户标识(开放键:内核不解释语义,只把非空值当作作用域)。
//
// 任务身份是 (Tenant, ID):同一 ID 在不同租户下是两条互不相干的任务。
// 空值 = 默认/单租户命名空间(旧行为:身份退化为 ID,存储键布局不变)。
// 租户段的键由实现生成,调用方**不要**把租户拼进 ID(见包文档「多租户」)。
Tenant string `json:",omitempty"`
// ID 任务标识(在租户作用域内唯一)。
ID TaskID
// Title 展示用标题。
Title string
// Deps 依赖的任务 id(全部完成才可认领)。
Deps []TaskID
// State 当前状态。
State State
// Owner 当前认领者(仅 StateClaimed 时有值)。
Owner AgentID
// Lease 当前租约(仅 StateClaimed 时有值)。
Lease Lease
// Seq 单调递增序号(宿主用它做 CAS 与留痕;本包只要求它随变更增大)。
Seq uint64
}
Task 一个子任务。
**不是可安全复制的值类型**:Deps 是切片,`t2 := t1` 只复制切片头,改写 t2.Deps 的元素会改穿 t1(也不能用 == 比较——含切片的 struct 在 Go 里 不可比较)。跨边界交出前必须 Clone(等价于深拷贝 Deps);Board 实现 返回快照时的拷贝义务写进了 Board 契约(issue #379)。