Documentation
¶
Overview ¶
backend.go —— 协调后端的最小原语契约(适配形态约定的代码面)。
为什么是这四个原语,而不是更多 ¶
把 taskboard.Board 与 sideeffect.Store 的判定逻辑推到底之后, 后端真正要提供的只有四件事:
- **快照读**:一次取多键的一致视图(判定所需的全部状态,同一瞬间);
- **条件事务**:全部断言成立才提交全部写入,否则一个都不执行 (「一次原子操作」的通用形态——Redis 的 Lua、etcd 的 txn、 PG 的事务条件更新都是它的实例);
- **前缀扫描**:一次原子操作取回前缀下**全部键与值**(issue #182—— 全量视图类操作的读面。「列键 + 逐键快照」两步拼接不是一致快照, 两步之间新增/删除的任务既不出现在结果里也不报错);
- **前缀列键**:只列键名(宿主自己的枚举需要;需要「键+值」同刻视图 一律走 ScanSnapshot,不要 Keys+Snapshot 两步拼)。
少一个:没有快照读就得逐键读,一致性窗口从「一次」变成「N 次」; 没有条件事务就没有原子提交,三判合一必然退化成三步三写; 没有前缀扫描,全量列举就得「列键 + 快照」两步拼——那是一致性窗口 被「两次调用」重新打开(#182 的缺陷本体)。 多一个:锁、watch、租约原语都不需要——那些语义已经由适配器在原语之上 组合实现,后端多给只会引入第二份真相。
版本(Version)是断言的锚点 ¶
条件事务的断言形态刻意取「版本相等」而不是「值相等」:版本由后端在 **每次成功写入时 +1**(单调不回退),等值断言等价于「自我上次快照后 这个键没被动过」。值相等断言在 ABA 场景(改走又改回)会误判「没动过」, 版本断言不会——这与 commitgate「凭令牌认占用」是同一条纪律: 用变更的次数而不是变更后的内容认变更。
board.go —— taskboard.Board 的**通用适配器**:判定逻辑落在 Backend 原语之上。
判定逻辑只有这一份 ¶
Board 的语义(认领原子、凭令牌释放/完成、续期是资格检查、接管代次严格 递增)全部在本适配器里实现;宿主的后端只负责让四个原语真的原子。 判定与提交分离的窗口由断言护住:判定读过的每个键都进断言, 窗口内被人动过就取新快照重判——这就是「CAS 循环」形态在 Board 上的落法。
令牌由适配器在提交路径上铸造 ¶
token 每次认领尝试用 crypto/rand 现铸:断言保证只有铸这枚令牌的那次 事务能提交,输家的令牌从不落库——「由存储铸造」的本意(凭据出自判定面, 不由调用方自带)由此成立。到期时刻由**存储的时钟**算(Backend 的 ClockSource 原语,与 examples/pgstore「到期由存储时钟算」同一口径—— 调用方的时钟与存储的时钟可能对不上,跨进程时更不能假设一致); UseClock 只留给契约套件做过期场景(issue #194:生产路径不得注入本地时钟)。
依赖键的动态展开 ¶
认领判定要读依赖任务的状态,而依赖清单在任务记录里——首轮快照只有 任务键。这里不假装键集是静态的:首轮解码出依赖后重取一次快照 (把依赖键一并纳入断言面);认领期间拓扑被改(断言失败)时按新清单 再展开。拓扑变更在运行期是病态事件,多花一次快照读比漏护一扇窗便宜。
board_internal.go —— Board 适配器的内部件(键集构造 / 断言面 / 解码 / 凭据铸造)。 从 board.go 拆出:结构阈值(400 行)按判据的一侧切——适配器的判定入口 与它们消费的内部件分开,两边各自可读。
board_renew.go —— Board 适配器的续期入口(含判定—提交窗口事实, issue #271)。从 board.go 拆出:结构阈值(400 行)按判据的一侧切, 续期(资格检查)与认领/收尾入口各自可读。
cas.go —— CAS 循环与并发原子性判据(适配形态约定的执行面)。
casLoop:判(快照)与写(事务)之间的窗口通用收尾 ¶
快照读与条件事务是两次后端交互——之间有窗口,别的进程可能改了状态。 适配器不假装窗口不存在:断言失败就取新快照重判,收敛为止。 上限只是防挂死的兜底(持续冲突 = 有高频写者或后端没实现原子性, 显式报 ErrTxnConflict,不无限重试)。
ConcurrentTxn:原语原子性的可跑判据 ¶
「Txn 的断言与写入不可分割」是 Backend 的**契约条款**,不是实现细节。 与 taskboard.ConcurrentClaim 同一形态:写成导出判据,宿主的后端实现 跑一遍即算验过——两个进程内竞争者同时断言同一版本、各自写不同的值, 恰好一个提交成功、版本只前进一格。断言与写入分离的坏实现 (先查后写没有原子性)在这里必红。
claimready.go —— taskboard.ReadyBoard 的适配器实现(issue #189)。
判定仍只有一份 ¶
批量领取不另写认领状态机:候选挑选按一份 List 快照做,每一笔认领都走 BoardAdapter.Claim(原子读-判-写、令牌与代次铸造、过期接管、依赖判定 全部复用)。批量只是「一次快照挑多个候选 + 逐个提交」,输在竞争的那一笔 跳过、继续下一笔——与单条 Claim 的竞争性拒绝同一条处置。
为什么仍读全量快照 ¶
通用 Backend 原语没有「就绪索引」这一面(四个原语是快照/条件事务/ 前缀扫描/列键),所以参考实现只能从全量视图挑候选。批量化的收益是 **把每拍的认领次数从 1 提到 n**(列表调用频率随之下降 n 倍);真正 按索引领取(列表量不随任务总量放大)要由宿主后端自己实现 ReadyBoard ——契约在 taskboard,适配器只是可用的参考形态。
Package coord 分布式协调后端的**适配形态约定**:一个后端要接上本仓的 协调契约(taskboard.Board / sideeffect.Store),要按什么形状表达 「一次原子操作」「条件更新」「CAS 循环」。
生命周期: Experimental(v0.35.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
它补的是哪一段(issue #107) ¶
本仓的协调契约全部是**存储中立**的:sideeffect.Store / taskboard.Board / checkpoint.StoreCAS 只定语义,实现由宿主提供。真实后端的参考适配此前只有 PostgreSQL 一种(examples/pgstore)——「后端不止一种,且形态有约定」 那一半是空的:宿主接 Redis / etcd 时没有任何形态可抄,各自发明 「读-判-写」三步实现,把跨进程原子性写丢(sideeffect 包头警告的头号窗口)。
本包把形态收成**一条代码级的约定**而不是一篇散文:
- @@Backend@@:协调后端的最小原语集(快照读 / 条件事务 / 前缀扫描 / 前缀列键)。 任何后端(Redis / etcd / 单机文件)只要实现这四个方法,
- @@BoardAdapter@@ / @@StoreAdapter@@:把契约的三判合一、资格联查、 执行意图等**全部判定逻辑**落在原语之上——判定逻辑只有这一份实现, 宿主的后端只负责让原语真的原子。
于是「接一个新后端」的工作量从「重写一遍 Store 的 29 条契约语义」 缩成「实现四个原语 + 让它们在存储侧真的原子」。
形态约定:四种原语在各后端怎么表达 ¶
- **快照读(Snapshot)**:一次取多键的一致视图。 Redis → 一条 Lua 脚本内 MGET(脚本内无并发写);etcd → 一个只读 txn (shared 读,同 revision);PostgreSQL → 一条 SELECT(单语句一致性)。
- **条件事务(Txn)**:全部断言成立才执行全部写入,否则一个都不执行。 Redis → Lua 脚本(单线程执行天然原子;断言写在脚本开头,不满足即返回 0); etcd → txn(If 全部成立才 Then);PostgreSQL → 事务内的 SELECT … FOR UPDATE + 条件 UPDATE。
- **前缀扫描(ScanSnapshot)**:一次原子操作取回前缀下全部键与值(#182)。 Redis → 一条 Lua 内 SCAN+MGET(或 KEYS+MGET,脚本内无并发写); etcd → 一个只读 txn 内 range(同 revision 天然同刻);PostgreSQL → 一条 `SELECT … WHERE key LIKE prefix%`(单语句一致性)。 **不要 Keys + Snapshot 两步拼**:那是两次调用,键集在两步之间可以 增删,拼不出任何一刻的完整视图。
- **CAS 循环**:断言失败(applied=false)→ 取新快照 → 重判 → 再事务。 这是适配器的通用收尾:判(快照)与写(事务)之间有窗口,冲突就重来。 Redis 有 Lua 时整个判定可推进脚本里、免循环;etcd/PG 保留循环即可。
租户键布局与领取条件(issue #195) ¶
键只由适配器按作用域生成,调用方不拼租户:
- **单租户**(NewBoardAdapter,旧布局,逐字不变): coord/task/<id>、coord/taskfence/<id>;
- **租户作用域**(NewTenantBoardAdapter): coord/t/<escaped-tenant>/task/<id>、coord/t/<escaped-tenant>/taskfence/<id>。
为什么租户布局另起 coord/t/ 根,而不是 coord/task/<tenant>/<id>:旧布局 的任务 id 是任意字符串(可以含 '/'),后者会与「旧布局里 id 恰好是 <tenant>/<id> 的任务」撞键。键的唯一性与旧布局的逐字不变**只能同时成立** 当租户段有自己的根。租户段做转义(非 [A-Za-z0-9_-] 的字节一律 %XX), id 仍是该租户根下的不透明后缀——调用方把租户拼进 id 只会得到另一条 id, 不会改变作用域。
租户作用域适配器从 tenant.Context(ctx 通道)取租户:缺租户/空租户一律 tenant.ErrNoContext(与写路径同一道 fail-closed 闸);他租户任务在 List 里不可见、在 Claim/Release/Complete/Renew 上一律 taskboard.ErrNotFound (不可见 = 不存在,不泄露存在性)。Seed 按 Task.Tenant 落键(套件接缝; 生产创建语义归宿主)。
**边界**:本包只让任务板的键与领取条件可判定。副作用幂等键、事件流、 运行留痕/审计、数据库 RLS 仍归宿主——多租户宿主必须自己在那些面把租户 纳入身份/过滤条件(见 tenant 包「数据面落点」)。
各后端的原子性边界(能保证什么、不能保证什么) ¶
- **Redis**:单 Lua 脚本内的多键读写在脚本执行期间原子(单线程模型); 脚本之间无隔离保证——跨脚本的「读后写」必须整段进同一个脚本。 附加约束:集群模式下多键必须同 slot(hash tag);主从复制异步, 主挂时会丢已确认的写——用它当协调状态需要等价于共识的部署形态 (如 RedLock 的争议面),宿主自担。
- **etcd**:txn 的 If/Then/Else 是一次真正的原子比较交换,revision 全局 单调——天然适合当版本与栅栏。边界:性能量级远低于 Redis(raft 落盘), 不适合高频租约续期;watch 的语义边界(历史窗口)与本包无关。
- **PostgreSQL**:事务隔离下的条件更新(examples/pgstore 已示范)。 本包不重复它——那条路径的参考在 pgrefstore 模块。
- **内存(@@MemoryBackend@@)**:进程内互斥锁,**跨进程原子性不存在**。 只用于测试与演示——拿它上生产等于以为自己在去重,实际两个进程各做一次 (sideeffect 包头警告的原话)。它在本包的用途是给适配器当测试保底: 让「判定逻辑这份实现」在没有真实后端时也能被契约套件验证。
租约误差预算:判定时刻与提交时刻的窗口(issue #271) ¶
issue #194 解决的是「时间从哪里来」(存储时钟 / 仅单机声明的节点时钟), 本段解决的是「读到的时刻与提交是否在同一瞬间」。普通续期路径是 「读存储时刻 → 快照 → 判定 → 条件事务」:两次后端交互之间存在窗口, 窗口内租约可能到期,而本副本仍按旧快照提交续期成功。这不是两套时间 真相,是「承诺的时间上界说不清」。
两条路径与可查事实:
- **原子路径**:后端实现 @@AtomicDecision@@,在一次事务内取存储时刻、 读快照、判定并提交。判定与提交的窗口为 0(@@LeasePrecision.Atomic@@ = true,Window = 0);窗口内到期必被拒绝。
- **误差预算降级路径**:后端未实现 AtomicDecision。判定—提交窗口按 @@DefaultLeaseErrorBudget@@ = **250ms** 承诺,时间来源为**存储时钟** (@@TimeSourceStorageClock@@;仅单机声明的后端为节点时钟)。适配器 显式标记 @@LeasePrecision.Degraded@@ = true,并在每次续期后由 @@RenewWithVerdict@@ 返回 @@LeaseVerdict@@:实际窗口、旧到期时刻是否 落在窗口内(ExpiredInWindow)、是否超出预算(BudgetExceeded)以及 @@Warning@@ 文案。**降级路径不阻止过期持有者提交**——它只把风险 变成可解释、可观测的事实;需要严格保证的宿主必须让后端原子化。
装配期的时间权威检查(@@ErrNoTimeAuthority@@)保持不变:原子判定接缝 是**能力加法**,不是时间权威的替代品——两者都没有的后端仍拒绝装配。
与「判定逻辑单份实现」的边界声明 ¶
本包是**机制**:适配器的判定逻辑(判据归内核)+ 原语契约(原子性归存储)。 它**不是**「一份生产可用的存储」——单靠本包什么都没有, 必须有一个真原子的 Backend 才成立。这与 sideeffect「不给参考存储实现」 的纪律不冲突:那份纪律拦的是「内存实现被当成生产存储」, 本包的内存后端只垫在**判定逻辑**与**契约套件**之间,且在类型名上写明边界。
memory.go —— Backend 的内存参考实现(**单进程演示保底,不得上生产**)。
边界刻在名字与文档里 ¶
MemoryBackend 的原子性来自**进程内互斥锁**:四个原语在锁内逐字原子, 但那只对同一进程成立。拿它当生产协调存储 = 两个进程各持一把各自的锁, 「Acquire 是跨进程原子操作」这条前提不存在——sideeffect 的全部判据 会显示为绿,而去重已经失效(AGENTS.md「参考实现是可被误用的资产」 那条纪律的原话场景)。
它在本包的用途只有两个:①给适配器(Board/Store)当**测试保底**—— 判定逻辑那份实现由契约套件验证时,不需要真实后端;②给宿主当 **形态示范**——照它的四个方法写 Redis/etcd 版本。
monotonic.go —— Backend **版本单调契约**的可跑判据(issue #181)。
为什么删除也要判 ¶
「版本是断言的锚点」立论的前提是版本随每次成功写入推进且**永不复用**。 删除丢版本的实现(条目随删,同名键重建后版本从 1 重来)会制造教科书 ABA:快照读到 k@1 ⇒ 另一路删 k ⇒ 重建 k ⇒ 旧断言 k@1 重新成立 ⇒ 提交成功——判定读的是「上一代的值」,提交写的是「新一代的键」,而且 **看起来都提交成功**,宿主侧没有任何信号。
本判据把「写 → 删 → 重建 → 旧版本 CAS 必须失败」钉成红线。与 taskboard/boardtest 同一口径的共享契约:宿主接 Redis/etcd/PG 时对 自己的 Backend 实现跑同一套,不为任何实现开后门。
precision.go —— 租约「判定时刻—提交」窗口的可查事实(issue #271)。
它补的是哪一段 ¶
issue #194 已经要求「到期由存储时钟算」,装配期也拒绝拿不出时间权威的 后端。但那一条只管**时间来源**,不管**读取时刻与提交时刻是否重合**: 普通路径是「读存储时刻 → 快照 → 判定 → 条件事务」,两次后端交互之间 存在窗口。窗口内租约可能到期,而本副本仍按旧快照把续期提交成功。
本文件把这条窗口从「实现细节」变成两个可查事实:
- @@LeasePrecision@@:装配后即可查询的承诺——后端是否支持原子判定、 判定—提交窗口的上界、时间来源;
- @@LeaseVerdict@@:每次续期判定后的观测——实际窗口多长、是否在窗口内 越过到期时刻、是否超出预算。
原子后端(实现 @@AtomicDecision@@)窗口恒为 0;非原子后端走误差预算 降级路径,必须显式标记(Degraded),并允许宿主持有「这不是严格保证」 的口径。预算数值与来源写在 @@DefaultLeaseErrorBudget@@ 与 @@TimeSource@@。
record.go —— Store 适配器的记录形态与三项联查。 从 store.go 拆出(结构阈值按判据的一侧切):两份状态(Key 级 act / 资源级 res)的落库形态、编解码,以及「令牌是最新代 + 持有者是授予铸造 的那份 + 租约与动作资源一致」的联查口径——判定入口在 store.go, 它们消费的凭据语义在这里。
store.go —— sideeffect.Store 的**通用适配器**:判定逻辑落在 Backend 原语之上。
判定逻辑只有这一份 ¶
Store 的 29 条契约语义(三判合一、判定顺序「已完成 > 结果未知 > 执行中 > 资源被占 > 授予」、三项联查、执行意图、对账占用、Unsafe 显式放行)全部 在本适配器里实现。宿主的后端只负责让四个原语真的原子;判定与提交之间 的窗口由断言护住(判定读过的键全部列进断言,被人动过就重判)。
两份状态、两个键族 ¶
- act/<key> Key 级:这个动作做过没有 / 结果未知没有 / 有没有一次 尚未裁决的尝试(执行意图)/ 有没有人在对账;
- res/<resource> 资源级:这个资源谁占着 / 发第几代令牌。
两条出口分开(Abandon 动 Key 级 + 资源级,Release 只动资源级)在键族上 直接可见。栅栏令牌住在资源记录里:它只在授予(接管)时递增,释放不清零 ——「释放后的租约」凭旧令牌回来时,令牌仍是那一代但持有者已空, 三项联查的 ErrFenceStale 照样拦下。
标记失败必须保住执行意图 ¶
MarkUncertain 的契约硬要求(标记写失败时意图不得被撤)在本形态下由 **断言事务天然成立**:标记与「撤销意图」是同一事务里的写入, 事务失败 = 什么都没发生,意图原样挡着。
文件分工(结构阈值按判据的一侧切) ¶
本文件:装配 + 施加侧(Acquire——判定最重的一个入口);store_lease.go: 持有期收尾(Complete/Release/Abandon/Renew/MarkUncertain——凭凭据收尾); store_reconcile.go:对账裁决(凭下游事实不凭持有权)。
store_lease.go —— Store 适配器的**持有期收尾**侧(Complete / Release / Abandon / Renew / MarkUncertain)。从 store.go 拆出:结构阈值(400 行) 按判据的一侧切——施加侧(Acquire,判定最重)单独在 store.go, 这五个入口共享同一性质:**凭凭据收尾**(令牌/栅栏对得上才动状态, 收尾不重判授予),与裁决侧(store_reconcile.go,凭下游事实不凭持有权) 又是两回事。三个文件三份性质,各自可读。
store_reconcile.go —— Store 适配器的裁决侧(ResolveUncertain / BeginReconcile)。 从 store.go 拆出:裁决与对账占用是「结果未知」一族的方法面,与施加侧 (Acquire/Complete/...)的判定性质不同——裁决**不校验栅栏**(依据是下游 事实,不是持有权),单独成文件把这个差别写在眼前。
Index ¶
- Constants
- Variables
- func ConcurrentTxn(ctx context.Context, b Backend, key string, workers int) error
- func VersionNotReused(ctx context.Context, b Backend, key string) error
- type Assert
- type AtomicDecision
- type Backend
- type BoardAdapter
- func (a *BoardAdapter) Claim(ctx context.Context, id taskboard.TaskID, agent taskboard.AgentID, ...) (taskboard.Task, error)
- func (a *BoardAdapter) ClaimReady(ctx context.Context, agent taskboard.AgentID, n int, ...) ([]taskboard.Task, error)
- func (a *BoardAdapter) Complete(ctx context.Context, id taskboard.TaskID, token string) error
- func (a *BoardAdapter) LeasePrecision() LeasePrecision
- func (a *BoardAdapter) List(ctx context.Context) ([]taskboard.Task, error)
- func (a *BoardAdapter) Release(ctx context.Context, id taskboard.TaskID, token string) error
- func (a *BoardAdapter) Renew(ctx context.Context, id taskboard.TaskID, token string, ...) (taskboard.Task, error)
- func (a *BoardAdapter) RenewWithVerdict(ctx context.Context, id taskboard.TaskID, token string, ...) (taskboard.Task, LeaseVerdict, error)
- func (a *BoardAdapter) Seed(tasks ...taskboard.Task)
- func (a *BoardAdapter) TenantScoped() bool
- func (a *BoardAdapter) UseClock(now func() time.Time)
- type ClockSource
- type Entry
- type LeaseBudget
- type LeasePrecision
- type LeaseVerdict
- type MemoryBackend
- func (m *MemoryBackend) Keys(_ context.Context, prefix string) ([]string, error)
- func (m *MemoryBackend) ScanSnapshot(_ context.Context, prefix string) (map[string]Entry, error)
- func (m *MemoryBackend) SingleMachine() bool
- func (m *MemoryBackend) Snapshot(_ context.Context, keys ...string) (map[string]Entry, error)
- func (m *MemoryBackend) Txn(_ context.Context, asserts []Assert, mutations []Mutation) (bool, error)
- type Mutation
- type SingleMachine
- type StoreAdapter
- func (s *StoreAdapter) Abandon(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, _ string) error
- func (s *StoreAdapter) Acquire(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Outcome, sideeffect.Lease, sideeffect.Result, error)
- func (s *StoreAdapter) BeginReconcile(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Reconcile, error)
- func (s *StoreAdapter) Complete(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) (sideeffect.Result, error)
- func (s *StoreAdapter) LeasePrecision() LeasePrecision
- func (s *StoreAdapter) MarkUncertain(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) error
- func (s *StoreAdapter) Release(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease) error
- func (s *StoreAdapter) Renew(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) (sideeffect.Lease, error)
- func (s *StoreAdapter) RenewWithVerdict(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) (sideeffect.Lease, LeaseVerdict, error)
- func (s *StoreAdapter) ResolveUncertain(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
- func (s *StoreAdapter) ResolveUncertainOwned(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution, ...) (sideeffect.Outcome, sideeffect.Result, error)
- func (s *StoreAdapter) UseClock(now func() time.Time)
- type TimeSource
- type Version
Constants ¶
const DefaultLeaseErrorBudget = 250 * time.Millisecond
DefaultLeaseErrorBudget 非原子后端的**承诺误差预算**(issue #271)。
数值:250ms;来源:存储时钟(ClockSource.Now 与条件事务之间的一次 往返)。这个数不是测量值,而是本仓对「判定读到的时刻与提交时刻最多 差多少」的承诺上界:同地域、同一存储服务的条件事务往返通常在此量级内。 后端可以用 LeaseBudget 声明自己的真实上界;声明值 <= 0 视作未声明。
语义边界(重要):预算**不改变**判定逻辑,也不阻止过期持有者提交—— 它只把「可能发生的窗口」变成可解释、可观测的上界。需要严格保证的宿主 必须让后端实现 AtomicDecision(窗口 0),或消费 LeaseVerdict 自行处置 超预算事实。
Variables ¶
var ErrMalformedRecord = errors.New("coord: 记录解码失败(键下内容不是本适配器的编码)")
ErrMalformedRecord 键下的记录无法解码(后端里的字节与本包的编码不一致)。
它说明这批键不是本适配器写的(键前缀撞了,或后端被别的写者占用)—— 放行会把别人的字节当自己的状态判,静默给出错误结论。
var ErrNoTimeAuthority = errors.New("coord: 后端拿不出权威时间(未实现 ClockSource 也未声明仅单机),拒绝装配")
ErrNoTimeAuthority 装配期拒绝(issue #194):后端既不实现 ClockSource (租约/占用到期由存储时钟算)也未声明 SingleMachine(仅单机)。
适配器**不静默退化**成节点本地时钟:多副本下节点间时钟差会直接改写 「租约是否到期」的判定——快 30 秒的节点把还在跑的租约判成已过期、 第二个人认领成功(副作用被施加两次);慢的节点让真过期的租约没人接。 拿不出权威时间就在装配时说清楚,不把「两套时间真相」留给运行期。
var ErrTxnConflict = errors.New("coord: 条件事务反复冲突,重试上限内未提交")
ErrTxnConflict CAS 循环重试到上限仍未提交(高争用或后端行为异常)。
循环上限是防挂死的兜底:正常争用几次内必收敛;持续冲突说明有调用方 在高频改同一批键(或后端根本没实现原子性),此时把冲突显式交上去, 不无限重试。
Functions ¶
func ConcurrentTxn ¶
ConcurrentTxn 并发原子性判据:两个竞争者同时断言同一版本,恰好一个提交。
判法(与 taskboard.ConcurrentClaim 同一形态):
- 先取 key 的当前版本 v(不存在则 VerMissing);
- workers 个竞争者**同时**提交 Txn([key@v], 各自写自己的值);
- 成功者必须**恰好 1 个**(0 = 全被断言拒了,说明判据没测到争用; >1 = 断言与写入没有原子性,契约破);
- 其余必须 applied=false(正常输家);任何 error 都是基础设施故障, 显式报出,不混进「输家」里——把后端故障算成输家,判据会在后端 坏掉时变绿;
- 版本必须恰好 v+1(版本断言之外多写一格或少写一格都是版本语义破)。
返回的 error 只表示**基础设施故障或契约违反**,不表示「有人输」。
func VersionNotReused ¶ added in v0.39.0
VersionNotReused 版本单调契约判据:同一键「写 → 删 → 重建」全序列里 版本严格前进、永不复用,删除前(及重建前任何历史)版本做的断言对 重建后的键必须失败。
判法:
- 写入 v1,取版本 a;
- 删除:快照必须 Exists=false 且版本 > a——删除同样推进版本 (墓碑条目或全局修订号皆可,「删除后版本比删除前小或回 VerMissing」必红:锚点随删除丢失就是把它拆了);
- 重建 v2,取版本 c:必须 > a(不复用历史版本;c == a 即 ABA);
- 断言 k@a 的 CAS 必须**不生效**(applied=false),且键停在 c/v2 (失败的断言一个 Mutation 都不执行);
- 断言 VerMissing(「从未写过」)对重建后的键也必须不生效—— 「写过又删了」正是断言要拦的窗口。
返回的 error 只表示**契约违反或基础设施故障**,不表示断言失败 (第 4/5 步断言失败是**期望的结论**,不生效才算过)。
Types ¶
type Assert ¶
Assert 条件事务的断言:键的当前版本必须等于 Ver。
Ver = VerMissing 即断言「键从未写过」(防「快照时没有、提交时被别人 建了」的窗口);要断言「此刻不存在」,断言快照里读到的那个版本即可 (墓碑键快照返回 Exists=false + 墓碑版本,原样列进断言就是「自我上次 快照后这个键没被动过」)。断言的键与被写的键**必须同批提交**:断言 只护自己列出的键,没列出的键在快照与提交之间怎么变都不管——适配器要 把判定读过的键全部列进断言,少列一个就是少护一扇窗。
type AtomicDecision ¶ added in v0.43.0
type AtomicDecision interface {
// DecideTx 在一次事务内取存储时刻、读快照、执行判定并条件提交。
DecideTx(ctx context.Context, decide func(now time.Time, read func(keys ...string) (map[string]Entry, error)) (asserts []Assert, mutations []Mutation, err error)) (applied bool, at time.Time, err error)
}
AtomicDecision 后端的**原子判定**接缝(issue #271,可选能力)。
普通 Backend 的判定路径是「先读存储时刻 → 快照 → 判定 → 条件事务」: 读时刻与提交是两次后端交互,中间有时间窗口。窗口内租约可能已经到期, 而本副本仍按旧快照把续期提交成功——这不是「两个真相」,是「承诺的 时间上界说不清」。
实现本接口 = 承诺下面这件事在**一次存储事务内**完成:
取存储时刻 now → 交给 decide 读快照并给出断言/写入 → 条件提交
decide 收到的 now 就是该事务的提交时刻(实现必须取事务内时间, 例如 PostgreSQL 的 clock_timestamp()、Redis Lua 的 TIME),read 返回的 快照必须属于同一事务。断言失败返回 applied=false(正常结论,什么都没写); error 只表示基础设施故障。
实现了本接口的后端,租约判定与提交的窗口为 0(见 LeasePrecision); 未实现的后端走误差预算降级路径(见 DefaultLeaseErrorBudget)。
type Backend ¶
type Backend interface {
// Snapshot 一致快照读:返回这些键的当前状态。
// 同一个键重复出现按一次计;不存在的键返回 Exists=false 的条目。
Snapshot(ctx context.Context, keys ...string) (map[string]Entry, error)
// Txn 一次原子操作:全部 Assert 成立才执行全部 Mutation。
//
// 返回 applied=false 表示有断言不成立(什么都没发生)——这是**正常结论**
// 不是错误:CAS 循环的调用方取新快照重判即可。error 只表示基础设施故障。
Txn(ctx context.Context, asserts []Assert, mutations []Mutation) (applied bool, err error)
// ScanSnapshot 前缀扫描:一次原子操作取回前缀下全部**存活键**的键与值
// (issue #182,全量视图类操作的读面——BoardAdapter.List 用它取「同刻
// 全集」)。墓碑键(已删除)不返回——与 Keys 的可见性同一口径。
//
// 「原子」= 键集与值出自同一瞬间(后端自己的锁/事务/脚本内),调用方
// 拿到的 map 就是那一个时刻的完整视图,不存在「先看到的键在取值时已被删」
// 的拼接缝。每次成功写入(含删除)推进版本的同一条纪律在这里同样成立:
// 扫描结果里每个条目的 Ver 都是扫描那一刻的版本。
ScanSnapshot(ctx context.Context, prefix string) (map[string]Entry, error)
// Keys 列出前缀下的全部键名。
//
// 注意(issue #182 后的口径修正):本方法**只供宿主自己枚举键名**。
// 「键名 + 值」的同刻视图必须走 ScanSnapshot——先 Keys 再 Snapshot 是
// 两次独立调用,两次之间键集可以增删,拼出来的既不是全量也不是任一时刻
// 的视图。适配器内不再这样拼(List 已收口到 ScanSnapshot)。
Keys(ctx context.Context, prefix string) ([]string, error)
}
Backend 协调后端的最小原语契约。
实现方必须保证(这四条是「接上协调契约」的全部硬要求):
- Txn **原子**:全部 Assert 成立时执行全部 Mutation 并把被写键的版本 各 +1;任一断言不成立时**一个 Mutation 都不执行**(返回 false);
- Snapshot **一致**:返回的是同一瞬间的视图(后端自己的锁/事务/脚本内);
- ScanSnapshot **一致且原子**:键集与值来自**同一次原子操作**(issue #182 ——「列键 + 快照」两步之间新增/删除的键既不进结果也不报错,那是 跨两个时刻的拼接,不是快照);
- Version **单调**:同一键的版本随每次成功写入严格 +1,不回退、不复用 ——写入含 Del(删除同样推进版本,见 Version)。
典型实现形态见包文档的「形态约定」节。跨进程原子性由实现方的存储保证 ——本包的内存后端只在单进程内成立,不得上生产。
type BoardAdapter ¶
type BoardAdapter struct {
// contains filtered or unexported fields
}
BoardAdapter 把任意 Backend 适配成 taskboard.Board(含 RenewingBoard)。
func NewBoardAdapter ¶
func NewBoardAdapter(b Backend) (*BoardAdapter, error)
NewBoardAdapter 构造**单租户**任务板适配器(旧布局;默认路径零回归)。
单租户适配器不解释 ctx 里的租户上下文:键恒为 coord/task/<id> 与 coord/taskfence/<id>。要做多租户隔离必须显式用 NewTenantBoardAdapter (装配期可见,不静默切换作用域)。
func NewTenantBoardAdapter ¶ added in v0.39.0
func NewTenantBoardAdapter(b Backend) (*BoardAdapter, error)
NewTenantBoardAdapter 构造**租户作用域**任务板适配器(issue #195)。
所有 Board 操作从 tenant.Context(ctx 通道)取租户:
- 缺租户/空租户 ⇒ tenant.ErrNoContext(fail-closed,与写路径同一口径);
- 键由作用域生成(coord/t/<escaped-tenant>/task/<id>),调用方不拼租户;
- List 只含本租户任务;Claim/Release/Complete/Renew 对他租户任务一律 taskboard.ErrNotFound(不可见 = 不存在,不泄露存在性)。
空租户与缺租户不是一回事:空租户是**单租户适配器**的默认命名空间; 租户作用域适配器拒绝空租户。
func (*BoardAdapter) Claim ¶
func (a *BoardAdapter) Claim(ctx context.Context, id taskboard.TaskID, agent taskboard.AgentID, req taskboard.ClaimRequest) (taskboard.Task, error)
Claim 认领一个任务(读-判-写窗口由断言护住,冲突即重判)。
代次与认领在同一事务里推进(fenceKey +1 + 任务落库,同一次原子操作铸造)。
func (*BoardAdapter) ClaimReady ¶ added in v0.39.0
func (a *BoardAdapter) ClaimReady(ctx context.Context, agent taskboard.AgentID, n int, req taskboard.ClaimRequest) ([]taskboard.Task, error)
ClaimReady 实现 taskboard.ReadyBoard:一次快照挑出就绪候选,按任务 id 序逐个认领,直到领满 n 个或候选耗尽。
竞争性拒绝(ErrTaken / ErrBlocked / ErrTerminal / ErrNotFound)跳过并 继续下一笔;其它错误中止,**已领到的任务仍随返回值交给调用方**(错误 只说明本轮没取满)。
func (*BoardAdapter) LeasePrecision ¶ added in v0.43.0
func (a *BoardAdapter) LeasePrecision() LeasePrecision
LeasePrecision 报告本适配器的租约判定精度承诺(issue #271)。
装配后调用一次即可:Atomic=true ⇒ 判定与提交不重合(窗口 0); Atomic=false ⇒ 走误差预算降级路径,Window 是承诺上界(Budget), 每次判定后的实际窗口用 RenewWithVerdict 观测。
func (*BoardAdapter) List ¶
List 返回**同刻全量视图**(issue #182):一次 ScanSnapshot 取回前缀下 全部键与值(键集与值出自同一原子操作),逐键解码后按任务 ID 序返回。
为什么不能 Keys + Snapshot 两步拼:那是两次独立调用,两次之间新增/删除的 任务既不出现在结果里也不会让任何断言失败——「一致快照」的承诺与实现直接 矛盾,受害的是全量视图类消费(worker.claimNext 的候选挑选、恢复扫描、 配额核算、运维看板)。原语契约见 Backend.ScanSnapshot。
func (*BoardAdapter) Renew ¶
func (a *BoardAdapter) Renew(ctx context.Context, id taskboard.TaskID, token string, req taskboard.ClaimRequest) (taskboard.Task, error)
Renew 续期并确认持有资格(taskboard.RenewingBoard):令牌不匹配或已过期 都报 ErrLeaseLost 且不做任何修改——续期不是心跳,是资格检查。
需要每次判定的窗口事实(是否在窗口内过期、是否超预算)时用 RenewWithVerdict;本入口保持 taskboard.RenewingBoard 的原签名。
func (*BoardAdapter) RenewWithVerdict ¶ added in v0.43.0
func (a *BoardAdapter) RenewWithVerdict(ctx context.Context, id taskboard.TaskID, token string, req taskboard.ClaimRequest) (taskboard.Task, LeaseVerdict, error)
RenewWithVerdict 同 Renew,并返回判定—提交窗口的观测事实(issue #271)。
后端实现 AtomicDecision 时,取存储时刻与提交在同一事务内(窗口 0, 窗口内过期必被拒绝);否则走误差预算降级路径——续期仍可能按旧快照 提交,但 verdict 会给出实际窗口、旧到期时刻是否落在窗口内、是否超预算, Warning 可直接写审计/日志。
func (*BoardAdapter) Seed ¶
func (a *BoardAdapter) Seed(tasks ...taskboard.Task)
Seed 摆初始任务(boardtest 契约套件的接缝:契约本身没有「创建」入口, 任务拓扑是宿主资产)。
套件的接缝签名没有 error(与 reference-runtime 的内存板同口径):任务体是 纯数据、编码不会失败;摆入的后端故障只能静默——这个方法不是生产 API, 生产路径的任务落库在宿主自己的装配代码里。
func (*BoardAdapter) TenantScoped ¶ added in v0.39.0
func (a *BoardAdapter) TenantScoped() bool
TenantScoped 报告适配器是否为租户作用域(装配期决策的投影)。
宿主可在启动自检里断言「多租户部署拿到的是租户作用域适配器」—— 单租户适配器与租户适配器的构造器不同,这条断言把「忘记装配」变成 启动期失败,而不是运行期的跨租户可见。
func (*BoardAdapter) UseClock ¶
func (a *BoardAdapter) UseClock(now func() time.Time)
UseClock 注入时钟(boardtest 契约套件要求:过期判定必须读可注入的时钟)。
仅限测试:契约套件的过期场景用它做确定性推进。生产路径**不得**注入本地 时钟——租约到期是跨进程共享的事实,时间真相在存储(issue #194)。
接缝契约(issue #369) ¶
@seam: no-reentry no-blocking panic-caller
- **不得重入**:回调内不得再次触发会读取本适配器时钟的判定路径(会递归); 只读回查是安全的——时钟在 a.mu 之外被调用(issue #317)。
- **不得阻塞**:回调在每次判定前被调用,必须立即返回。
- **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。
type ClockSource ¶ added in v0.39.0
ClockSource 权威时间原语(issue #194):租约/占用的「到期时刻」由**存储 自己的时钟**算——调用方的时钟与存储的时钟可能对不上,跨进程时更不能 假设一致。这是 examples/pgstore 的硬纪律(「到期由存储时钟算」)在 Backend 这个更通用的接缝上的同一落法:多副本下两个节点时钟差 30 秒, 用节点时钟判「租约已过期」就是让第二个人在第一个人还在跑时认领成功。
实现形态示例:Redis → Lua 脚本内 TIME;PostgreSQL → 事务内 clock_timestamp()(examples/pgstore 即此形态);etcd → 以 revision 或 专门的存储侧时间键为锚。拿不出权威时间的后端见 SingleMachine。
type Entry ¶
type Entry struct {
// Key 键名。
Key string
// Ver 当前版本(从未写过的键为 VerMissing;被删除过的键为墓碑
// 版本,随每次写入与删除推进、不回退不复用)。
Ver Version
// Val 当前值(键不存在时为 nil)。后端不得复用底层字节——
// 返回的切片必须是快照那一刻的独立拷贝。
Val []byte
// Exists 键是否存在(墓碑键 Exists=false,但 Ver 仍可读)。
Exists bool
}
Entry 一次快照读到的键状态。
type LeaseBudget ¶ added in v0.43.0
LeaseBudget 后端可声明的**判定—提交窗口预算**(issue #271,可选能力)。
未实现时适配器按 DefaultLeaseErrorBudget 承诺。实现本接口的后端应当 按自己的真实事务往返(含存储时钟读取)声明上界;返回值 <= 0 视作未声明。 只能声明、不能验证——实际窗口由 LeaseVerdict 在每次判定后观测。
type LeasePrecision ¶ added in v0.43.0
type LeasePrecision struct {
// Atomic 判定时刻与提交是否在同一存储事务内。
Atomic bool
// Degraded 是否走误差预算降级路径(Atomic=false 时恒为 true)。
Degraded bool
// Window 判定—提交窗口的承诺上界:原子后端为 0,非原子后端等于 Budget。
Window time.Duration
// Budget 后端声明或本仓缺省的误差预算(原子后端也保留该声明,便于观测)。
Budget time.Duration
// Source 时间权威来源。
Source TimeSource
}
LeasePrecision 租约判定的承诺精度(装配后即可查询的事实,不是散文)。
type LeaseVerdict ¶ added in v0.43.0
type LeaseVerdict struct {
// Atomic 本次判定是否走了原子路径。
Atomic bool
// Observed 非原子路径是否成功观测到提交后的存储时刻
// (读不到时 Window/BudgetExceeded 不可解释,只能标为未观测)。
Observed bool
// Source 时间权威来源。
Source TimeSource
// Budget 本次判定适用的误差预算。
Budget time.Duration
// DecidedAt 判定读到的存储时刻(原子路径 = 事务内时刻)。
DecidedAt time.Time
// CommittedAt 提交后的存储时刻(原子路径 = DecidedAt)。
CommittedAt time.Time
// Window 判定—提交实际窗口(非负;原子路径为 0)。
Window time.Duration
// ExpiredInWindow 本次判定所依据的租约到期时刻落在窗口内
// (即提交时租约已经到期,判定依据的是过期快照)。
ExpiredInWindow bool
// BudgetExceeded 实际窗口超过承诺预算。
BudgetExceeded bool
}
LeaseVerdict 一次续期判定的窗口观测(issue #271)。
原子路径下 DecidedAt == CommittedAt、Window == 0;非原子路径下 CommittedAt 是提交后重读的存储时刻,Window 是两次读之间的实际差。 其余字段是把「窗口内发生了什么」问清楚的机器可判事实。
func (LeaseVerdict) Warning ¶ added in v0.43.0
func (v LeaseVerdict) Warning() string
Warning 返回可解释告警;无异常时返回空串。
非原子路径的异常必须能被宿主直接写进日志/审计,而不是只留下 「续期成功了」这一条看不出风险的事实。
type MemoryBackend ¶
type MemoryBackend struct {
// contains filtered or unexported fields
}
MemoryBackend Backend 的进程内实现(见文件头的边界声明)。
func (*MemoryBackend) Keys ¶
Keys 前缀列键(锁内快照语义,结果按键名排序保证确定性)。 墓碑键不列——已删除的键不在键空间里(列出去,适配器的 List 会把 已删任务当活任务判)。
注意:本方法只列键名。需要「键 + 值」的同刻视图走 ScanSnapshot(#182), 不要 Keys + Snapshot 两步拼。
func (*MemoryBackend) ScanSnapshot ¶ added in v0.39.0
ScanSnapshot 前缀扫描:锁内一次取回前缀下全部存活键的键与值(#182)。
「一次原子操作」在这里字面成立:整个遍历在同一把锁内完成,调用方拿到的 map 是**同一个瞬间**的键集与值——遍历中途的并发写入要么整体发生在扫描前、 要么整体发生在扫描后,不存在半新半旧的拼接。墓碑键不返回(与 Keys 同一 可见性口径);结果按键名排序保证确定性;Val 是独立拷贝(与 Snapshot 同一条「后端不得复用底层字节」的纪律)。
func (*MemoryBackend) SingleMachine ¶ added in v0.39.0
func (m *MemoryBackend) SingleMachine() bool
SingleMachine 仅单机声明(issue #194):进程内互斥锁就是它的全部原子性, 时间真相只有节点本地时钟——显式声明给装配器看,适配器才允许用它判到期 (并继续给契约套件留 UseClock 注入的口子)。它同时重申本类型的边界: 不得上生产。
type SingleMachine ¶ added in v0.39.0
type SingleMachine interface {
// SingleMachine 报告后端是否只在单进程内使用。
SingleMachine() bool
}
SingleMachine 仅单机声明:拿不出权威时间的后端在**装配期**显式声明 「只在单进程内使用」,适配器才允许用节点本地时钟判到期——单进程内只有 一个时钟,不存在跨进程不一致。不声明也不实现 ClockSource 的后端 **拒绝装配**(@@ErrNoTimeAuthority@@),不静默退化成节点时钟。
type StoreAdapter ¶
type StoreAdapter struct {
// contains filtered or unexported fields
}
StoreAdapter 把任意 Backend 适配成 sideeffect.Store。
func NewStoreAdapter ¶
func NewStoreAdapter(b Backend) (*StoreAdapter, error)
NewStoreAdapter 构造 Store 适配器。
装配期检查时间权威(issue #194):后端既不实现 ClockSource 也不声明 SingleMachine 时返回 @@ErrNoTimeAuthority@@——占用/意图/对账的到期判定 同样是跨进程共享的事实,拒绝装配,而不是静默退化成节点本地时钟。
func (*StoreAdapter) Abandon ¶
func (s *StoreAdapter) Abandon(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, _ string) error
Abandon 显式放弃本次尝试:撤销执行意图 + 释放资源持有(资源闸只在 仍是自己的时才放——易主了就不碰,那是新持有者的闸)。
func (*StoreAdapter) Acquire ¶
func (s *StoreAdapter) Acquire(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Outcome, sideeffect.Lease, sideeffect.Result, error)
Acquire 一次原子判定。判定顺序是契约里最要紧的一行: **已完成 > 结果未知 > 执行中 > 资源被占 > 授予**。 顺序写反的代价是重复施加:把「结果未知」排到「资源被占」之后, 调用方会拿到 contended(以为「晚点重试就行」),重试于是发生。
func (*StoreAdapter) BeginReconcile ¶
func (s *StoreAdapter) BeginReconcile(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Reconcile, error)
BeginReconcile 认领对账权(同一 Key 同一时刻至多一个对账者; 占用过期可重入——对账者死亡不永久占住这个 Key)。
func (*StoreAdapter) Complete ¶
func (s *StoreAdapter) Complete(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, res sideeffect.Result) (sideeffect.Result, error)
Complete 标记完成并留存结果(幂等:先到者的结果不被后到者覆盖; 三项联查通过才接受)。
func (*StoreAdapter) LeasePrecision ¶ added in v0.43.0
func (s *StoreAdapter) LeasePrecision() LeasePrecision
LeasePrecision 报告本存储适配器的占用/意图续期精度承诺(issue #271)。
func (*StoreAdapter) MarkUncertain ¶
func (s *StoreAdapter) MarkUncertain(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, reason string) error
MarkUncertain 把该 Key 标记为「结果未知」(按键,与资源租约无关)。 标记与「撤销意图」在同一事务里:事务失败 = 什么都没发生, 意图原样留在存储里挡着后续 Acquire(契约硬要求第 5 条)。 标记成功后闸**不**自动释放——调用方显式 Release 只放资源。
func (*StoreAdapter) Release ¶
func (s *StoreAdapter) Release(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease) error
Release 释放资源持有,**不动** Key 级的执行意图——意图没被裁决之前, 这个 Key 不得再被执行(「施加成功但进程死在记账之前」的封口)。
func (*StoreAdapter) Renew ¶
func (s *StoreAdapter) Renew(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ttl time.Duration) (sideeffect.Lease, error)
Renew 续期并确认持有资格:闸已易主、尝试已失效**或租约已过期**则拒绝 续期(假续期延长的是别人的闸——重复施加的入口)。
func (*StoreAdapter) RenewWithVerdict ¶ added in v0.43.0
func (s *StoreAdapter) RenewWithVerdict(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ttl time.Duration) (sideeffect.Lease, LeaseVerdict, error)
RenewWithVerdict 同 Renew,并返回判定—提交窗口的观测事实(issue #271)。 原子后端(AtomicDecision)窗口 0;非原子后端按误差预算降级并留下 窗口内过期/超预算的可解释事实。
func (*StoreAdapter) ResolveUncertain ¶
func (s *StoreAdapter) ResolveUncertain(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
ResolveUncertain 裁决「结果未知」的 Key(先到者为准;**不校验栅栏**—— 它的依据是下游事实,不是持有权,对账恰恰要在持有者死亡后进行)。 简化入口不校验对账凭据——短对账无须认领,跨进程长对账走下面的 ResolveUncertainOwned。
func (*StoreAdapter) ResolveUncertainOwned ¶
func (s *StoreAdapter) ResolveUncertainOwned(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution, holder string) (sideeffect.Outcome, sideeffect.Result, error)
ResolveUncertainOwned 带对账占用凭据的裁决(OwnedResolveStore): holder 不是**当前有效**对账认领的持有者 → ErrReconcileLost,不改任何状态。
校验与裁决同一事务:CAS 断言保证判定读到的占用就是裁决要落的那份—— 「校验时还有效、裁决前已被接管」的窗口由断言失败重判兜住。
func (*StoreAdapter) UseClock ¶
func (s *StoreAdapter) UseClock(now func() time.Time)
UseClock 注入时钟(sidetest 契约套件要求:过期判定必须读可注入的时钟)。
仅限测试:契约套件的过期场景用它做确定性推进。生产路径**不得**注入本地 时钟——占用到期是跨进程共享的事实,时间真相在存储(issue #194)。
接缝契约(issue #369) ¶
@seam: no-reentry no-blocking panic-caller
- **不得重入**:回调内不得再次触发会读取本适配器时钟的判定路径(会递归); 只读回查是安全的——时钟在 s.mu 之外被调用(issue #317)。
- **不得阻塞**:回调在每次判定前被调用,必须立即返回。
- **panic 由调用方兜**(panic-caller):内核不 recover 该回调的 panic。
type TimeSource ¶ added in v0.43.0
type TimeSource string
TimeSource 租约判定使用的时间权威来源(issue #271 要求写明三选一)。
const ( // TimeSourceStorageClock 存储时钟(ClockSource;原子判定事务内时刻 // 也属于这一档)。 TimeSourceStorageClock TimeSource = "storage_clock" // TimeSourceMonotonicSequence 存储侧单调序列(etcd revision 一类; // 当前适配器未使用,保留词表以免宿主自造字符串)。 TimeSourceMonotonicSequence TimeSource = "monotonic_sequence" // TimeSourceLocalClock 节点本地时钟(仅 SingleMachine 声明下成立)。 TimeSourceLocalClock TimeSource = "local_clock" )
type Version ¶
type Version uint64
Version 键版本:每次成功写入 +1,单调不回退,由后端保证。
「成功写入」**含删除**(issue #181):Del 同样推进版本——版本是断言的 锚点,随条目一起删掉就是把它拆了。实现可保留墓碑条目(Exists=false + 版本),也可用全局修订号/单调 CAS 序号做锚点;但下面这条**没有实现 自由**:删除后同名键重建,拿删除前(或重建前任何历史)版本做的断言 必须失败——「写 v → 删 → 重建 → 旧版本 CAS 必失败」由 @@VersionNotReused@@ 判据钉住,宿主换 Redis/etcd/PG 跑同一套。
const VerMissing Version = 0
VerMissing 从未写过的键的版本(0;新键首写后从 1 起)。
只表示「从未写过」:被删除过的键携带墓碑版本(> VerMissing)且 Exists=false——对它断言 VerMissing 不成立。这是刻意为之(ABA 防线): 「快照时没有、提交时之前被人写过又删了」正是断言要拦住的窗口。