taskreg

package

v0.21.0 Latest Latest Go to latest Published: Aug 26, 2026 License: MIT Imports: 4 Imported by: 0

Details

Package taskreg 提供 Worker 侧「运行中长任务内存登记表」（FR-183，见 ADR-040）。

长任务（如 JDK 安装）启动即返回 task_id 后，后台 goroutine 经本登记表持续更新进度/日志；心跳每周期把表内任务快照随心跳上报给 CP。任务进入终态（succeeded/failed）并被心跳上报后由心跳侧调用 Drop 从表内移除（已落 CP，无需再报）。

多协程安全：后台执行 goroutine 写、心跳 goroutine 读，全程加锁。

This section is empty.

This section is empty.

This section is empty.

type Registry struct {
	// contains filtered or unexported fields
}

Registry 运行中任务的线程安全登记表。零值不可用，须经 New 创建。

func New() *Registry

New 创建空登记表。

func (r *Registry) AppendLog(taskID, line string)

AppendLog 追加一行日志，赋予全局单调递增的绝对序号（超过上限则丢弃最旧行，序号不重置）。任务不存在则忽略。

func (r *Registry) Cancel(taskID string) bool

Cancel 强制停止任务（FR-227）：调用其执行 context 的 cancel（真中断下载等操作）并置 canceled 终态。仅对运行中任务生效（已终态/不存在返回 false，幂等——心跳可能重复下发同一 id）。

func (r *Registry) Drop(taskID string)

Drop 从登记表移除任务（终态被心跳上报后调用）。

func (r *Registry) Fail(taskID, errMsg string)

Fail 把任务置为 failed，errMsg 为失败原因。已被 Cancel 置 canceled 的任务不再被覆盖（终态守卫，FR-227）。

func (r *Registry) SetProgress(taskID string, progress int32)

SetProgress 更新任务进度（0~100）。任务不存在则忽略。

func (r *Registry) Snapshot() []*workerpb.TaskSnapshot

Snapshot 返回当前所有任务的快照（用于心跳上报）。返回的切片与底层状态解耦，可安全跨协程使用。

func (r *Registry) Start(taskID string, cancel context.CancelFunc)

Start 登记一个新任务为 running（progress=0）。cancel 用于强制停止时真中断执行（FR-227，可为 nil）。重复 taskID 覆盖。

func (r *Registry) Succeed(taskID, result string)

Succeed 把任务置为 succeeded（progress=100），result 为成功结果 JSON。已被 Cancel 置 canceled 的任务不再被覆盖（终态守卫，FR-227）。