taskboard

package
v0.46.1 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 10 Imported by: 0

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. 把到期时刻推后(长动作不至于中途失去闸);
  2. 校验令牌仍是该任务的最新一代——不是则拒绝,**不做任何修改**。

只做第 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

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

View Source
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 认人)。

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

func LeaseHeld(t Task, now time.Time) bool

LeaseHeld 报告任务当前是否仍被**活持有**(issue #335 的单点判据)。

判定 = 认领态 **且** 租约未过期(Until 零值 = 不限期,按在持判——当成 已过期会让「两个执行者同时认领」变成「两个赢家」)。

为什么收敛成导出函数:此前 coord / examples 的两个参考实现 / controlplane 各写一份等价判据,而 controlplane.MemStore.Claim **压根没判过期**—— 持有者进程崩掉后任务被永久占用,与 Board.Claim 的「被别人**活着**持有」 契约方向相反。存储实现的 Claim 必须调用本函数,不得各写一份(第二份 判据必然漂移)。

Types

type AgentID

type AgentID string

AgentID 执行者标识。

**允许重复**(并行分支常同名)——这正是「凭 token 不凭内容」的理由。

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 一次认领的凭证。

func (Lease) IsZero added in v0.39.0

func (l Lease) IsZero() bool

IsZero 报告租约是否为全零值(没有残留任何一列)。

判定收敛在此处而不是散落各处(issue #220):快照体检要判「非认领态是否 残留租约」,漏一列(Until)就让「体检绿」与运行期行为分叉——今后再加 字段时,这里是一处改、处处跟的单点。

type Problem

type Problem struct {
	// Tenant 相关任务的租户(空 = 默认/单租户命名空间)。
	Tenant string `json:",omitempty"`
	// Task 相关任务 id。
	Task TaskID
	// Code 机器可判的类别(宿主按它分流与留痕)。
	Code string
	// Text 人读的说明。
	Text string
}

Problem 一条快照不变量违反。

func Check

func Check(tasks []Task) []Problem

Check 判一份快照的**不变量**,按 (Tenant, Task, Code) 排序返回(确定性)。

这是宿主随时能跑的「体检」:不必等出问题,配置加载、每个调度周期都可以跑; 它判的是**状态自身是否自相矛盾**,不判「策略对不对」。

快照可以混合多个租户:判重按 (Tenant, ID),依赖只在同租户内解析。 报告行的 Problem.Tenant 指明问题属于哪个租户(空 = 默认命名空间)。

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 任务状态。

const (
	// StateOpen 待认领。
	StateOpen State = "open"
	// StateClaimed 已被认领(owner + lease 必须有值)。
	StateClaimed State = "claimed"
	// StateDone 已完成(终态)。
	StateDone State = "done"
	// StateFailed 已失败(**非终态**——允许重新认领:失败的工作通常要重做)。
	StateFailed State = "failed"
)

func AllStates added in v0.43.0

func AllStates() []State

AllStates 返回任务状态词表的全集(排序后的**新切片**)。

宿主据此渲染任务状态选择器 / 校验落库值,不必手抄常量清单。

注意 done 与 failed 的**词表成员身份**与**终态身份**是两件事:failed 在 词表内但非终态(可重新认领,见 State.Terminal),枚举出口给的是词表成员 集合,不是终态集合。

func (State) Claimable added in v0.43.0

func (s State) Claimable() error

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

func (s State) Terminal() bool

Terminal 报告该状态是否**不可再被认领**。

只有 done 是终态:failed 的任务必须能重做,否则一次失败就把子任务永久钉死, 而宿主的补救路径(重新派一个人)会静默失效。

**failed 在词表上非终态,这是刻意的**(见 StateFailed 的常量注释,issue #375): 常量注释曾写「终态」,与本函数相反;两处现在逐字对齐。体检面同样按本函数 判:failed + 残留 owner 不报 CodeTerminalClaimed,failed 也不算「依赖已完成」。

func (State) Valid added in v0.43.0

func (s State) Valid() bool

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)。

func (Task) Clone added in v0.43.0

func (t Task) Clone() Task

Clone 返回任务的深拷贝:Deps 换一份底层数组,其余字段值语义直接复制。

用途是跨边界交出(Board 实现返回 List/Claim 快照、宿主把任务传出自己的 存储层):仓库内三个实现各自手写了同款 `slices.Clone(t.Deps)`/等价的 逐条 append,这里给出**单一口径**,契约不再依赖每个实现各自记得写 (issue #379)。

type TaskID

type TaskID string

TaskID 子任务标识。

Directories

Path Synopsis
Package boardtest @@Board@@ 的**共享契约测试套件**。
Package boardtest @@Board@@ 的**共享契约测试套件**。

Jump to

Keyboard shortcuts

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