Documentation
¶
Overview ¶
db.go —— 共享事务域:一把锁、一个日志、一次提交。
四个面(任务板 / 副作用闸 / 进度快照 / 事件行)共用这一份 db:进程内 mutex(单写者)+ 跨进程 flock(见 lock_*.go),写日志只有一条 append 路径。⇒ 「同一把锁、同一个日志」不是约定,是**只有一条写路径**这件事 的直接后果。
判定读的是**重放后的最新状态**,不依赖进程内缓存——重启后第一件事就是 重放,崩溃不会让「谁占着任务」这件事出现两个答案。
Package sqlitestore Standalone 部署形态的**单机持久化参考实现**: 任务板(taskboard.Board + RenewingBoard)、副作用闸(sideeffect.Store)、 进度快照(checkpoint.StoreCAS)、事件面(eventbus.Store + TailStore + WatermarkTailStore)**四个面共用一份事务域**——同一把锁、同一个日志、 一次提交。
生命周期: Experimental(v0.39.0 定级)——参考实现,随契约套件与参考部署 演进,不承诺任何兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级 规则见 docs/api-compat.md。
依赖纪律:为什么这里没有 SQLite 驱动(先读这段) ¶
issue #188 要的是 SQLite(WAL) 适配器。但本仓是**单一 Go module**(examples 不是独立 module,`go test ./...` 从根跑),而主干依赖面有一条硬纪律: 内核包不得为参考实现引入第三方依赖。go.mod 里唯一为示例破例的驱动是 pgx/v5(examples/pgstore),它在 architecture-policy.yaml 里登记为 「只进 pgrefstore 的依赖图」并有注释说明。
引入 modernc.org/sqlite(纯 Go,无 cgo)在技术上可行,但它会新增一个 **数 MB 的传递依赖树**到主 module,且 sqlite 的版本会随工具链/安全发布 漂移——为了一个示例性适配器付这份维护成本,不满足「依赖面窄」的判据。 故本包采用任务允许的替代方案:
- **契约级设计**:SQLite 的落库形态(DDL / WAL 参数 / 事务边界 / 单连接写串行化 / 时钟口径)完整写在下面的「SQLite 落库形态」一节, 宿主在自己的 module 里加驱动后可以逐条照抄;
- **可运行的最小文件后端**:`Store` 用 **flock 串行化 + JSONL 追加 + fsync** 实现同一套语义。它不是 SQLite,但它是**同一份契约的另一种 落法**——boardtest 与 sidetest 全套判据在它身上真跑,证明这些语义 在本机单写者形态下可满足。
明确不承诺:本包不是多副本共享协调库。数据目录放 NFS / 对象存储让多台 机器共同写,等于让「单写者」前提失效——多副本协调一律用 PG(与 examples/pgstore 的分工)。
四个面与一份事务域(issue #419) ¶
四个面不是四份数据,而是**同一份事务日志重放出来的四个投影**:
面 契约 入口 任务板 taskboard.Board/Renewing Store.Claim / Complete / … 副作用闸 sideeffect.Store Store.Effects().Acquire / … 进度快照 checkpoint.StoreCAS Store.Snapshots().SaveIfNewer / … 事件面 eventbus.Store/TailStore Store.Events().Insert / ListAfter / …
它们共用一把进程内 mutex + 一把跨进程 flock、一个日志文件、一次 fsync。 更要紧的是:**跨面的变更能落在同一次提交里**(`Store.Apply`)——任务 状态、副作用闸、进度快照、事件行写在日志的**同一行**里(journal.go 的 v2 批次格式)。⇒ 跨面不会出现「一半已提交」:要么整批可见,要么整批 不可见。
事件 ID 取自**已提交水位线**(铸造序 == 提交序,回滚不烧号)⇒ 序列空洞 结构性地不存在 ⇒ TailStore 的「无空洞推进」硬要求由构造满足,而不是靠 「读的时候小心别跳过」这种约定。
SQLite 落库形态(宿主抄这一节) ¶
打开数据库后先执行(顺序有意义):
PRAGMA journal_mode = WAL; -- 读不阻塞写,崩溃后按 WAL 重放 PRAGMA synchronous = FULL; -- 提交即落盘(单机可恢复的前提) PRAGMA busy_timeout = 5000; -- 跨进程写锁的等待上限(不静默丢写)
连接池只有**一个**写连接(database/sql 的 db.SetMaxOpenConns(1);读可以 另开只读连接池,WAL 允许读写并发)。所有写事务用 `BEGIN IMMEDIATE` 开局 ——它是「先拿写锁再干活」,避免 defer 到 COMMIT 才升级锁导致的 SQLITE_BUSY 半途失败。四个面各自的表(宿主按自己的字段裁剪):
CREATE TABLE IF NOT EXISTS board_task (
id TEXT PRIMARY KEY,
title TEXT NOT NULL DEFAULT '',
deps TEXT NOT NULL DEFAULT '[]', -- JSON 数组
state TEXT NOT NULL,
owner TEXT,
token TEXT,
fence INTEGER NOT NULL DEFAULT 0, -- 接管代次水位(释放不清)
until_unix INTEGER, -- 毫秒;NULL = 不限期
seq INTEGER NOT NULL DEFAULT 0
);
判据落库与 pgstore 的 board.go 同形:
- Claim:`BEGIN IMMEDIATE` → SELECT 任务行与依赖行 → 判终态/依赖/活租约 → 铸令牌与 fence(`fence = fence + 1`)→ UPDATE → COMMIT。读-判-写 在同一个写事务里,跨进程赢家恰好一个(boardtest.ConcurrentClaim 判)。
- Release / Complete:`UPDATE ... WHERE id=? AND token=? AND state='claimed'`, RowsAffected==0 ⇒ 再读一次区分 ErrNotFound / ErrLeaseLost;只认令牌。
- Renew:同一事务内校验 token + 未过期,再写 until_unix;过期即资格终止 (ErrLeaseLost),不建第二套时钟判据。
- 到期时刻用**数据库时钟**(`unixepoch('subsec')*1000` 或 Go 侧传入的 存储时钟),不用进程本地 time.Now——跨进程不假设时钟一致。
副作用闸的两级状态(Key 级 / 资源级)见 pgstore 的 effect*.go;进度快照 的单调写见 checkpoint/cas.go;事件面的水位线见 eventbus/tail.go。三者的 判据都不在本包重写——本包只提供**落库形态**。
本包文件后端的对应关系:
SQLite WAL 帧 + fsync ⇔ tasks.jsonl 的一行 + file.Sync() BEGIN IMMEDIATE / 写锁 ⇔ flock(LOCK_EX) 包住「重放 → 判 → 追加」 崩溃后 WAL 重放 ⇔ 打开/写入前重放 JSONL,截断未换行的残尾 db.SetMaxOpenConns(1) ⇔ 进程内 mutex(跨进程靠 flock) PRAGMA busy_timeout ⇔ lockTimeout(拿不到锁显式报错,不丢写) 一个事务 = 一行 ⇔ journal.go 的 v2 批次(跨面原子性)
已知边界(宿主照抄时要一起带上) ¶
- **重放是 O(n)**:每次事务都从头重放整个日志。参考实现够用,生产宿主 用 SQLite 就是 O(1) 索引查找——这不是语义差别,是量级差别。
- **载荷的数字会变成 float64**:事件载荷经 JSON 往返后数字统一为 float64("计数": 3 读回来是 3.0)。与 examples/pgstore 的 JSONB 同款; 需要整数保真就走字符串或宿主自己的序列化。
- **日志文件名没改**:文件里现在装的不止任务(四个面的批次),但名字 仍是 tasks.jsonl——改名会让宿主已有数据目录看起来是空的(比报错更难 查)。
- **写入粒度是整个事务**:一个批次一行 ⇒ 文件会随事务数线性增长, 且没有日志压缩。生产宿主用 SQLite 的表结构。
它是什么、不是什么 ¶
是:单机 + 可恢复形态的**契约级参考**(重启后四个面的状态都在;半截写 被丢弃;并发认领只有一个赢家;跨面变更同生共死)。不是:SQLite 本身的 绑定、查询优化、多副本协调。宿主的生产实现应照「SQLite 落库形态」一节 写,而不是把本包的 JSONL 文件格式当成生产存储协议。
effect.go —— 副作用面(sideeffect.Store)的判定内核。
这份内核钉住的三条判据 ¶
- **三项联查**:Renew / Complete / MarkUncertain / Abandon / Release 都必须校验「令牌仍是最新代 + 持有者身份与授予时铸造的一致 + 租约与 动作的资源一致」。只比栅栏令牌是不够的:释放闸之后令牌**没有变** (栅栏只在接管时递增),于是「释放后的租约」能拿同一枚令牌继续续期、 继续记账;令牌还会经下游流转(FencedSink),见过的组件拿着令牌就能 冒充持有者——持有者身份是授予时**存储侧铸造**的第二份凭据。
- **执行意图**:Acquire 授予执行权时原子登记「本次尝试还在」;租约过期 且未裁决时,同一 Key 转入需对账态,而不是重新授予执行权。
- **对账占用**:BeginReconcile 同一时刻至多一个对账者,占用过期可重入; RetrySafetyUnsafe 的动作裁决「未生效」不解除阻塞(显式决策才放行)。
与内存参考实现的关系 ¶
判据逐条对齐 examples/reference-runtime(已过 sidetest 全套)——本文件是 它的**落库形态**:状态从日志重放,变更以「Key 级 + 资源级同一记录」的 形式落盘(一次原子操作面在存储侧成立)。
判定顺序是契约里最要紧的一行 ¶
已完成 > 结果未知 > 执行中 > 资源被占 > 授予。顺序写反的代价是重复施加: 把「结果未知」排到「资源被占」之后,调用方会拿到 contended(以为「晚点 重试就行」),重试于是发生。
effect_guard.go —— 副作用面的**判据辅助**(三项联查与暂存)。
单独成文件不是为了好看:effect.go 已经顶到「单文件 400 行」的结构阈值, 而这些辅助判据是**独立可读的一组**(它们是「谁有资格写」的全部口径)。
为什么每条判据只有一个判据点 ¶
三项联查在两个入口(资源闸 / 执行意图)各查一遍,但**判的是同一件事**: 「这份凭据是不是本次授予的那份」。两份各写一遍的话,改一处忘另一处 ⇒ 同一个错误有两个主人 ⇒ 改坏了一处,测试**看不出**区别(另一处还在判), 于是那条判据事实上没有承重夹具。
故下面三个 helper 各自是**唯一判据点**:资源闸与执行意图都调它。
effect_store.go —— 副作用面的对外接口(sideeffect.Store + OwnedResolveStore)。
本文件只是**装配**:判定在 effect.go,事务在 tx.go。两种装配:
- 独立事务(Store.Effects()):每次调用自己开一个事务;
- 事务内(Tx.Effects()):与其它面的变更落在同一次提交里。
两个入口调用**同一套判据函数** ⇒ 不会出现「换个入口语义就变」。
event.go —— 事件面(eventbus.Store + TailStore + WatermarkTailStore)。
游标从哪来:已提交水位线 ¶
事件 ID **不是**自增序列,而是「已提交水位线 + 1」:水位线只随**提交** 推进,事务回滚既不推它也不烧号(下一个事务重新从同一点派生)。
⇒ 铸造序 == 提交序 ⇒ **序列空洞结构性地不存在** ⇒ TailStore 的「无空洞 推进」硬要求由构造满足,而不是靠「读的时候小心别跳过」这种约定。
这也正是 eventbus 契约点名的**唯一被承诺支持的生产形态:Outbox**(事件 行与业务状态同事务提交)。本包用 Tx/Apply 提供这个形态:事件行与任务 状态、副作用闸、进度快照落在**同一行**日志里。
「自增/序列 ID 直读」显式不支持 ¶
BIGSERIAL + WHERE id > cursor 那种读法:乱序提交让迟到的小 ID 被游标 永久越过(丢帧),回滚烧号让空洞永不回填(尾随永久停摆)。本实现不 提供那种形态,也不假装提供。
载荷的往返口径(与 examples/pgstore 的 JSONB 同款) ¶
载荷是 map[string]any,经 JSON 往返后**数字统一为 float64**("计数": 3 读回来是 3.0)。宿主若需要整数保真,走字符串或宿主自己的序列化。这是 JSON 载荷存储的既有性质,不是本实现的取舍——两个参考实现口径一致。
journal.go —— 事务日志的读写与崩溃恢复(文件后端的「WAL 帧」)。
一行 = 一个事务批次(v2 格式) ¶
v2 把「一次事务里的全部记录」写成**一行**:跨面的变更(任务状态 + 副作用 闸 + 进度快照 + 事件行)在磁盘上也是**同一条记录**——要么整批可见,要么 整批不可见。这正是「同一把锁、同一个日志、一次提交」的机器形态:跨面 不会出现「一半已提交」。
v1 格式(一行 = 一条任务记录)**仍可读**:旧目录不必迁移,重放时按行形状 与版本号判别(v1 行没有 records 字段)。旧记录读进来后与新记录走同一条 应用路径(applyRecord)⇒ 只有一份「记录怎么变成状态」的算法。
残尾规则不变:只有**以换行结尾**的行才算已提交——崩溃留下的半截行在打开 / 下一次写入前被截掉(与 SQLite WAL 的「完整帧才重放」同一条口径)。
lock.go —— 跨进程写锁的平台无关部分(判定结构 + 释放重试)。
平台差异只有 errno 的取值与「怎么拿锁」;判定结构本身与平台无关 ⇒ 放在 无平台约束的文件里:**判据能在任何机器上被真跑**(Windows 专属的 errno 只在 Windows 上出现,但判据不必等到 Windows CI 才验)。
为什么要有这个文件:Windows 上「独占创建锁文件」失败有三种「被占用」的 表达(见 lock_windows.go),只认一种就会把正常并发误判成故障——错指路比 不指路更坏(v0.46.0 的 Windows CI 就是这样红的:20 路并发认领里有 1 路 独占创建拿到 ERROR_ACCESS_DENIED,整条用例判「非争用类错误」失败)。
snapshot.go —— 进度快照面(checkpoint.StoreCAS)。
判据只有两条,但都是硬的 ¶
- **严格递增**:只有当该 runID 已持久化的序号**严格小于**本次序号时才 写入,否则返回 ErrStaleSeq 且**不得写入**(不得部分写、不得覆盖)。 首次写入(无记录)视作已持久化序号为 0。
- **Seq == 0 必须被拒**:序号为 0 的快照不是一次真实提交。此前契约写 「Seq == 0 不参与单调判定」,被实现读成了「跳过判定照写」⇒ seq=0 反而成了**唯一能覆盖既有快照**的写:恢复点静默回退且不报错。
落库形态与内存参考实现(examples/reference-runtime 的 snapStore)同一 判据;跨进程的那一半由「判据在存储侧」保证——本实现的判定就在事务里, 进程内再加一层闸也不会让它漂。
state.go —— 事务域的**已提交状态**(重放后的真相)。
四个面(任务板 / 副作用闸 / 进度快照 / 事件行)共享这一份状态:它们不是 四份独立数据,而是**同一份事务日志重放出来的四个投影**。⇒ 「共用一份 事务域」不是约定,是结构——状态里根本没有「只更新了其中一面」这回事。
状态只从日志重建(replay),不在内存里长期累积:每次事务都从日志重放 一次,判定读的是重放后的最新事实(崩溃不会让「谁占着任务」出现两个 答案)。
store.go —— 存储实例入口 + 任务面(taskboard.Board + RenewingBoard)。
每个公开方法都是一次「加锁 → 重放 → 判 → 追加 → fsync」的事务:
- 进程内用 mutex(单写者),跨进程用 flock(见 lock_*.go);
- 判定读的是**重放后的最新状态**,不依赖进程内缓存——重启后第一件事 就是重放,崩溃不会让「谁占着任务」这件事出现两个答案;
- 令牌随机 128 位(跨进程不复用),接管代次是独立水位(释放/完成不清)。
任务面之外,Store 还给出另外三个面(Effects / Snapshots / Events)—— 它们**共享同一份事务域**(同一把锁、同一个日志),并可用 Apply 把四个面 的变更放进**同一次提交**。
tx.go —— 事务内的四个面(跨面同一次提交)。
为什么需要它 ¶
四个面各自都能独立提交,并不能证明「单一存储覆盖全部状态」——那还差 最要紧的一条:**跨面的变更必须能落在同一次提交里**。
- 任务板说「这一步完成了」,事件面要同时留下一条事件行(Outbox): 分两次提交 ⇒ 崩在中间 ⇒ 「事情做完了但没留痕」或「留痕了但没做完」;
- 副作用闸说「这个动作已生效」,快照面要同时推进进度:分两次提交 ⇒ 恢复点与事实对不上,重启后重复施加。
Apply 提供的正是这个:**一次事务、四个面、一次落盘**。事务内的变更整批 写进日志的**同一行**(journal.go 的 v2 格式)⇒ 磁盘层面也不会出现 「一半已提交」。
Index ¶
- type EffectStore
- func (e *EffectStore) Abandon(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) error
- func (e *EffectStore) Acquire(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Outcome, sideeffect.Lease, sideeffect.Result, error)
- func (e *EffectStore) BeginReconcile(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Reconcile, error)
- func (e *EffectStore) Complete(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) (sideeffect.Result, error)
- func (e *EffectStore) MarkUncertain(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) error
- func (e *EffectStore) Release(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease) error
- func (e *EffectStore) Renew(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ...) (sideeffect.Lease, error)
- func (e *EffectStore) ResolveUncertain(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
- func (e *EffectStore) ResolveUncertainOwned(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution, ...) (sideeffect.Outcome, sideeffect.Result, error)
- func (e *EffectStore) UseClock(now func() time.Time)
- type EventStore
- func (e *EventStore) CommittedWatermark(ctx context.Context) (uint64, error)
- func (e *EventStore) Insert(ctx context.Context, ev eventbus.Event) (uint64, error)
- func (e *EventStore) ListAfter(ctx context.Context, cursor uint64, limit int) ([]eventbus.Event, error)
- func (e *EventStore) MaxID(ctx context.Context) (uint64, error)
- type Option
- type SnapshotStore
- type Store
- type TaskStore
- func (t *TaskStore) Claim(ctx context.Context, id taskboard.TaskID, agent taskboard.AgentID, ...) (taskboard.Task, error)
- func (t *TaskStore) Complete(ctx context.Context, id taskboard.TaskID, token string) error
- func (t *TaskStore) List(ctx context.Context) ([]taskboard.Task, error)
- func (t *TaskStore) Release(ctx context.Context, id taskboard.TaskID, token string) error
- func (t *TaskStore) Renew(ctx context.Context, id taskboard.TaskID, token string, ...) (taskboard.Task, error)
- func (t *TaskStore) Seed(tasks ...taskboard.Task) error
- func (t *TaskStore) UseClock(now func() time.Time)
- type Tx
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EffectStore ¶ added in v0.48.0
type EffectStore struct {
// contains filtered or unexported fields
}
EffectStore 副作用面(sideeffect.Store + sideeffect.OwnedResolveStore)。
func (*EffectStore) Abandon ¶ added in v0.48.0
func (e *EffectStore) Abandon(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, reason string) error
Abandon 显式放弃本次尝试:撤销执行意图,并释放资源持有。
func (*EffectStore) Acquire ¶ added in v0.48.0
func (e *EffectStore) Acquire(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Outcome, sideeffect.Lease, sideeffect.Result, error)
Acquire 一次原子判定,返回「能否执行」与「若能执行则用哪一代令牌」。
func (*EffectStore) BeginReconcile ¶ added in v0.48.0
func (e *EffectStore) BeginReconcile(ctx context.Context, act sideeffect.Action, ttl time.Duration) (sideeffect.Reconcile, error)
BeginReconcile 认领对账权:同一键同一时刻至多一个对账者。
func (*EffectStore) Complete ¶ added in v0.48.0
func (e *EffectStore) Complete(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, res sideeffect.Result) (sideeffect.Result, error)
Complete 标记该键的动作已完成并记录结果(幂等:先到者为准)。
func (*EffectStore) MarkUncertain ¶ added in v0.48.0
func (e *EffectStore) MarkUncertain(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, reason string) error
MarkUncertain 把该键标记为「结果未知」。
func (*EffectStore) Release ¶ added in v0.48.0
func (e *EffectStore) Release(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease) error
Release 释放**资源持有**(闸),**不动**该键的执行意图。
func (*EffectStore) Renew ¶ added in v0.48.0
func (e *EffectStore) Renew(ctx context.Context, act sideeffect.Action, lease sideeffect.Lease, ttl time.Duration) (sideeffect.Lease, error)
Renew 续期并**同时确认持有资格**。
func (*EffectStore) ResolveUncertain ¶ added in v0.48.0
func (e *EffectStore) ResolveUncertain(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution) (sideeffect.Outcome, sideeffect.Result, error)
ResolveUncertain 裁决「结果未知」的键(先到者为准,不校验对账凭据)。
func (*EffectStore) ResolveUncertainOwned ¶ added in v0.48.0
func (e *EffectStore) ResolveUncertainOwned(ctx context.Context, act sideeffect.Action, res sideeffect.Resolution, holder string) (sideeffect.Outcome, sideeffect.Result, error)
ResolveUncertainOwned 带对账占用凭据的裁决:holder 不是当前有效对账 认领的持有者 → ErrReconcileLost(不改任何状态)。
实现了它 = 声明本存储支持跨进程长对账(sidetest 对缺失**硬失败**)。
func (*EffectStore) UseClock ¶ added in v0.48.0
func (e *EffectStore) UseClock(now func() time.Time)
UseClock 注入存储时钟(sidetest.ClockedStore 的接缝要求)。
type EventStore ¶ added in v0.48.0
type EventStore struct {
// contains filtered or unexported fields
}
EventStore 事件面(eventbus.Store + TailStore + WatermarkTailStore)。
实现了 WatermarkTailStore 即**声明**本存储是 Outbox 形态(事件行与业务 状态同事务提交、水位线随提交推进)。
func (*EventStore) CommittedWatermark ¶ added in v0.48.0
func (e *EventStore) CommittedWatermark(ctx context.Context) (uint64, error)
CommittedWatermark 已提交水位线(≤ 此值的游标 ID 已全部提交且可见)。
func (*EventStore) Insert ¶ added in v0.48.0
Insert 持久化一条事件并返回权威游标 ID。
传入事件的 ev.ID 是输入侧遗留值,**一律忽略**(游标由存储铸造)。
type SnapshotStore ¶ added in v0.48.0
type SnapshotStore struct {
// contains filtered or unexported fields
}
SnapshotStore 进度快照面(checkpoint.StoreCAS)。
两种装配:独立事务(Store.Snapshots())或事务内(Tx.Snapshots())。
func (*SnapshotStore) Load ¶ added in v0.48.0
func (s *SnapshotStore) Load(ctx context.Context, runID string) (checkpoint.Snapshot, error)
Load 无记录时返回 checkpoint.ErrNotFound(不得返回零值 + nil)。
func (*SnapshotStore) SaveIfNewer ¶ added in v0.48.0
func (s *SnapshotStore) SaveIfNewer(ctx context.Context, snap checkpoint.Snapshot) error
SaveIfNewer 仅当该 runID 已持久化的序号严格小于 snap.Seq 时才写入。
type Store ¶
type Store struct {
*TaskStore
}
Store 单机文件后端:四个面共享一份事务域。
⚠️ 单写者形态:一个目录同一时刻只有一个写事务(flock);不要把它放到 NFS/共享盘上当多副本协调库(见包文档「明确不承诺」)。
func Open ¶
Open 打开(或创建)一个单机存储目录。
打开时会先拿一次写锁做崩溃恢复:截掉未换行的残尾。目录可重复打开 (多个 Store 实例 = 多个客户端);每个事务重新拿锁并重放最新日志。
func (*Store) Apply ¶ added in v0.48.0
Apply 在**一个事务**里提交四个面的变更。
回调返回错误 ⇒ 整批丢弃(四面都没变);返回 nil ⇒ 四个面的变更作为 **一行**落盘(journal.go 的 v2 批次)⇒ 跨面不会出现「一半已提交」。
这是「单一存储覆盖全部状态」的机器形态:任务状态、副作用闸、进度快照、 事件行(Outbox)在同一次提交里落盘。
func (*Store) Effects ¶ added in v0.48.0
func (s *Store) Effects() *EffectStore
Effects 副作用面(与任务面共享同一份事务域)。
func (*Store) Events ¶ added in v0.48.0
func (s *Store) Events() *EventStore
Events 事件面(与任务面共享同一份事务域)。
func (*Store) Seed ¶
Seed 摆初始任务(任务拓扑是宿主资产;契约没有「创建」入口)。
与 pgstore.BoardStore.Seed 同形态:同 id 重摆覆盖内容并清租约,接管代次 水位保留;落库失败 panic(装载入口不容静默失败)。
func (*Store) Snapshots ¶ added in v0.48.0
func (s *Store) Snapshots() *SnapshotStore
Snapshots 进度快照面(与任务面共享同一份事务域)。
type TaskStore ¶ added in v0.48.0
type TaskStore struct {
// contains filtered or unexported fields
}
TaskStore 任务面(taskboard.Board + taskboard.RenewingBoard)。
两种装配:独立事务(Store 持有)或事务内(Tx.Tasks() 取得)。判据是 同一套函数(taskClaim / taskFinish / taskRenew)⇒ 两个入口不漂。
func (*TaskStore) Claim ¶ added in v0.48.0
func (t *TaskStore) Claim(ctx context.Context, id taskboard.TaskID, agent taskboard.AgentID, req taskboard.ClaimRequest) (taskboard.Task, error)
Claim 认领任务(读-判-写在同一个写事务里;令牌与代次由存储铸造)。
「取任务 + 判状态可认领」这两步留在**方法体内**:它是本实现的唯一认领 入口(独立事务与事务内两个装配都走这里),判据因此只有一个主人。依赖与 活租约的判定、铸令牌与写入交给 taskClaim(同一事务内)。
func (*TaskStore) Renew ¶ added in v0.48.0
func (t *TaskStore) Renew(ctx context.Context, id taskboard.TaskID, token string, req taskboard.ClaimRequest) (taskboard.Task, error)
Renew 续期并确认持有资格(令牌仍是最新代且租约未过期)。
type Tx ¶ added in v0.48.0
type Tx struct {
// contains filtered or unexported fields
}
Tx 一次事务的四个面(共享同一份状态与同一次提交)。
func (*Tx) Effects ¶ added in v0.48.0
func (tx *Tx) Effects() *EffectStore
Effects 副作用面(sideeffect.Store 的事务内形态)。
func (*Tx) Events ¶ added in v0.48.0
func (tx *Tx) Events() *EventStore
Events 事件面(eventbus.Store / TailStore 的事务内形态)。
func (*Tx) Snapshots ¶ added in v0.48.0
func (tx *Tx) Snapshots() *SnapshotStore
Snapshots 进度快照面(checkpoint.StoreCAS 的事务内形态)。