Documentation
¶
Overview ¶
Package deadline 会话级墙钟时限:shared 锚点跨续跑轮 + timed_out deny-by-default (issue #170,下沉自宿主 internal/engine/scheduler/handle.go 的轮内墙钟与锚点写入)。
生命周期: Experimental(v0.38.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
它回答什么 ¶
会话往往跨多轮(自动续跑/排队续跑):**总时限不能因续跑轮重置**。每次续跑 都新开一段时限的话,会话可以无限续跑下去。故:
- **锚点只写一次**:首轮认领成功后写 deadline_at(FirstClaimAt + Timeout);
- **续跑轮沿用同一锚点**(shared 模式):轮内 ctx 只拿锚点的**剩余**时长;
- **轮内 ctx 携带专属 cause**(ErrSessionDeadline):与用户取消、接管、 进程停机可区分(收尾路由见 Route);
- **过期锚点立即收敛**:认领排队窗口把余量耗完的续跑轮,认领迁移成功后 立即按 timed_out 收敛,**不进编排**(进去了也只是白跑一段)。
时限是**会话生命周期**的轴:进程活得好好的也会到点。
五路收尾路由与次序纪律(硬约束,Route 的测试钉住) ¶
原因值 结论 落什么 steer.ErrSteered takeover 不落终态回 created(由 steer.Run 续跑) ErrSessionDeadline timed_out 终态(deny-by-default:超时的产出不可信) 契约/宿主的用户取消哨兵 cancelled 终态 其余 ctx 已取消(进程停机) shutdown 不落终态,留给恢复循环/启动对账 ctx 未取消 none 无收敛动作
**timed_out 臂必须先于「ctx.Err() != nil(进程停机)」臂。** 停机臂的条件是 「ctx 已取消」,而墙钟到点的 ctx 同样已取消(DeadlineExceeded)——次序写反, 每次会话超时都会被判成停机、**不落终态**,会话永久滞留 running。
**这条路由表只有一份**(issue #355):finalize.Route 是它的 Outcome→Action 投影,不再另写一遍 cause 判定与臂序。此前两包各写一份、零交叉断言,接管的 同一 ctx 在 deadline 判 shutdown(不落终态)、在 finalize 判 takeover (落 created)——两个相反结论取决于调用哪个包。
父 ctx 取消时子 ctx 的 Cause 传播父原因,故「用户取消/停机」不会被墙钟 装饰吃掉——五路的前提是各有自己的 cause(用户取消请用 context.WithCancelCause(contract.ErrUserCancelled) 表达,裸 cancel 与停机 在 Cause 上不可分)。
与同域包的划界(各占一根轴,互不改判据) ¶
- **vs budget**:budget 是资源/窗口压力面(token/上下文水位);本包是 墙钟时限(时间轴、跨轮锚点)。一根轴都不沾——不碰 budget 的判据, 也不把时限塞进 budget。
- **vs drain**:drain 是**进程**生命周期的在途轮收敛(停机排水);本包是 **会话**生命周期的总时限。drain.ErrDeadline 与本包 ErrSessionDeadline 是两个 Cause,收尾路由(Route)只认本包的哨兵,不认排水预算。
- **vs finalize**:finalize 是收尾**动作**漏斗(Converge 多起点收敛 / AdjudicateRetry 排队裁决);它的 Route 只做本包 Outcome→Action 投影, cause 判定与臂序(timed_out 先于停机)不在那边第二遍(issue #355)。
- **vs watchdog**:监视不变量,不做时限强制。
- **vs contract**:contract 给了 StatusTimedOut 词表(本包的 Outcome.Status 缺省消费它),没有时限机制——本包补机制不改词表;宿主自有状态词表经 StatusOf/StatusWith 注入(issue #237),缺省路径逐字不变。
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoStore = errors.New("deadline: 未注入锚点持久化接缝(Store),无法读写会话墙钟锚点")
ErrNoStore 未注入锚点持久化接缝就要读/写锚点。
fail-closed 而不是静默跳过:shared 模式下漏写锚点 = 续跑轮各自新开一段时限, 「总时限不被续跑轮刷新」这条契约**静默失效**,且没有任何信号。
var ErrSessionDeadline = contract.ErrSessionDeadline
ErrSessionDeadline 会话级墙钟超时的原因值(轮内 ctx 经 WithTimeoutCause 携带)。
识别一律走 errors.Is(可被宿主的包装链包裹);与 drain.ErrDeadline (停机排水超时)是**两个** Cause、两根轴,不要互相代入。
身份来自 contract.ErrSessionDeadline(issue #333):本变量是**别名**而不是 第二份 errors.New——收尾侧 finalize.Route 用同一个值做判定,errors.Is 一条链打通;各写一份同名同文案的哨兵会让墙钟超时被判成停机。
Functions ¶
func DefaultStatusOf ¶ added in v0.39.0
DefaultStatusOf 缺省映射:**消费 contract 的词表**,不另造一份。
不写状态的两档(None / Shutdown)返回空串:空串即「本轮没有状态要写」, 宿主据此跳过状态迁移,而不是写一个空状态。Takeover 返回 created—— 它是回迁目标(可认领态),不是终态,但仍是收尾动作要写的状态。
独立导出是为了让宿主能「只覆盖个别档、其余仍走缺省」——在注入的 StatusOf 里回落本函数即可(见 StatusWith)。
Types ¶
type Anchor ¶
type Anchor struct {
// FirstClaimAt 首次认领成功时刻(写入时生成,只写一次)。
FirstClaimAt time.Time
// DeadlineAt 绝对截止时刻 = FirstClaimAt + Timeout。续跑轮沿用它,
// **绝不刷新**——刷新等于把总时限重新计时。
DeadlineAt time.Time
}
Anchor 会话墙钟锚点(首轮认领成功后写一次,续跑轮读)。
func Persist ¶
func Persist(ctx context.Context, s Store, c Config, existing *Anchor, now time.Time) (*Anchor, error)
Persist 首轮认领成功后的锚点落位:**只在该写时写一次**,返回实际写入的锚点。
非 shared / 0=关闭 → 不写(锚点不参与) existing 已有锚点(续跑轮)→ 不写(沿用,绝不刷新——总时限不因续跑轮重置) existing 已过期 → 不写(该轮走立即收敛分支,轮不到这里) 其余(首轮认领成功) → 写 now+Timeout
Store 为 nil 且**确实需要写**时返回 ErrNoStore(fail-closed,见该哨兵注释)。
func Restore ¶
Restore 从注入的 Store 读锚点(未写 → (nil, nil))。
读失败**原样上抛**,不静默当「未写」:读不出锚点就装饰不了本轮剩余时长, 静默回落会给续跑轮新开一段 Timeout,把总时限静默重置。
type Config ¶
type Config struct {
// Timeout 会话级墙钟上限;**0=关闭**(直通:不装饰 ctx、不写锚点)。
Timeout time.Duration
// false=每轮各自开一段 Timeout(锚点不参与)。
Shared bool
}
Config 宿主注入的时限配置(宿主策略,语义与宿主 conf 旋钮一致)。
func (Config) Begin ¶
func (c Config) Begin(ctx context.Context, a *Anchor, now time.Time) (context.Context, context.CancelFunc, Constraint)
Begin 为本轮装饰墙钟 ctx:返回 (轮 ctx, 释放函数, 本轮时限形态)。
now 为当前时刻(宿主传 time.Now();判定与余量都以它为准)。
四种输入与返回值(issue #318:返回值必须能把前两者分开):
- **0=关闭直通**(Timeout<=0):原样返回 ctx,ConstraintOff—— 本轮**不受**约束,ctx 不带 Deadline;
- **shared 且锚点有效**:沿用同一锚点的剩余时长,ConstraintActive—— 总时限不因续跑轮重置;
- **shared 且锚点已过期**:不装饰,ConstraintExpired。宿主在**认领迁移 成功后**按 OutcomeTimedOut 收敛(不进编排),见包头次序纪律;
- **首轮(锚点未写)/ 非 shared**:新开一段 Timeout,ConstraintActive。
调用方判断「本轮是否受墙钟保护」一律看第三个返回值,**不要**用 ctx.Deadline() 推断:父 ctx 自带的 Deadline 会被误读成本包的约束。
release 非 nil 时必须 defer(释放定时器);ConstraintExpired 与 ConstraintOff 时 release 是空操作。
type Constraint ¶ added in v0.43.0
type Constraint int
Constraint 本轮时限形态(Begin 的返回值,issue #318)。
为什么不是 bool ¶
「本轮 expired 没有」只有两态,而本轮至少有三态:**关闭直通**(Timeout<=0, 本轮无限跑、ctx 不带 Deadline)、**受约束**(装饰了 Deadline)、**已过期** (不装饰,认领后立即收敛)。前两者用 bool 表达时返回值完全相同,调用方无法 从返回值判断本轮有没有墙钟保护——只能去猜 ctx.Deadline(),而父 ctx 自带的 Deadline 会污染这个信号。
这里复用包内已有的三态判定面(Anchor.State)的决策结果,只把「锚点三态」 投影成「本轮形态」:StateUnwritten/Live → ConstraintActive,StateExpired → ConstraintExpired,Timeout<=0 → ConstraintOff。
const ( // ConstraintOff 本轮**不受**时限约束(Timeout<=0 的关闭直通):ctx 原样返回。 ConstraintOff Constraint = iota // ConstraintActive 本轮受约束:ctx 带本包装饰的 Deadline(新开或锚点剩余)。 ConstraintActive // ConstraintExpired 本轮已过期:不装饰,宿主认领迁移后立即按 timed_out 收敛。 ConstraintExpired )
func (Constraint) Constrained ¶ added in v0.43.0
func (c Constraint) Constrained() bool
Constrained 本轮是否有墙钟保护(受约束或已过期都算——已过期只是余量为 0)。
func (Constraint) Expired ¶ added in v0.43.0
func (c Constraint) Expired() bool
Expired 本轮是否已过期(仅 ConstraintExpired)。
func (Constraint) String ¶ added in v0.43.0
func (c Constraint) String() string
String 机读名(进日志与测试断言)。
type Outcome ¶
type Outcome int
Outcome 收尾路由的结论(接管 / 超时 / 取消 / 停机,见包头表)。
本枚举是**唯一判据**的结论面(issue #355):finalize.Action 是它的动作投影, 两包不再各写一份路由表。
const ( // OutcomeNone ctx 未取消(正常编排中,没有收敛动作)。 OutcomeNone Outcome = iota // OutcomeTimedOut 会话墙钟到点:落 timed_out 终态。 // // deny-by-default 家族——超时轮的产出是**没跑完**的,不可信: // 不得落 succeeded,也不得借排队续跑把死 ctx 再跑一轮。 OutcomeTimedOut // OutcomeCancelled 用户/调用方显式取消:落 cancelled 终态。 OutcomeCancelled // OutcomeShutdown 进程停机:**不落终态**(running/waiting_approval 留给 // 恢复循环/启动对账收敛),也不写失败报告——停机不是这次编排的结论。 OutcomeShutdown // OutcomeTakeover 接管(steer.ErrSteered):**不落终态回 created**。 // // 与停机臂的语义相反:停机是「这一轮不收敛」,接管是「这一轮由新输入 // 续跑」——归 created 交给 steer.Run 承接。deadline 此前不认识这个 cause, // 同一 ctx 在 deadline 判 shutdown、在 finalize 判 takeover(issue #355)。 // // 追加在末尾(不插队):既有结论的数值不因新增臂而漂移。 OutcomeTakeover )
func Route ¶
Route 收尾段的五路路由(**唯一判据**;finalize.Route 是它的动作投影, issue #355)。
五路 ¶
接管(steer.ErrSteered) takeover 不落终态回 created 会话墙钟(ErrSessionDeadline) timed_out 终态 用户取消(契约/宿主哨兵) cancelled 终态 其余 ctx 已取消(进程停机) shutdown 不落终态,留给恢复循环 ctx 未取消 none 无收敛动作
次序纪律(硬约束) ¶
**timed_out 臂必须排在停机臂(`ctx.Err() != nil`)之前。** 墙钟到点时 ctx 同样已取消(DeadlineExceeded),停机臂的条件对它同样成立——次序写反, 每次会话超时都会被判成停机、不落终态,会话永久滞留 running。 测试里用「已取消 + cause=ErrSessionDeadline」的 ctx 钉住(该 ctx 同时满足 停机臂的条件,走错臂当场红)。**这一条判据只在本函数存在**:finalize 只做 Outcome→Action 的投影,不再另写路由表与臂序。
接管臂最先、用户取消臂先于超时臂:两者都是显式意图(新输入续跑 / 用户 主动停止),与墙钟同时出现时不把会话判成 timed_out(与 finalize 既有 臂序一致)。timed_out 与 shutdown 的相对次序仍是硬约束。
五路的前提是各有自己的 cause:
- 墙钟:WithTimeoutCause(..., ErrSessionDeadline)(本包 WithCause);
- 用户取消:context.WithCancelCause(contract.ErrUserCancelled)(全仓唯一 身份,缺省即认),宿主自有哨兵可经 userCancel 追加;
- 接管:context.WithCancelCause(steer.ErrSteered)(steer.Signal);
- 停机:父 ctx 取消传播下来的 cause(或裸 cancel)。
裸 cancel 与停机在 Cause 上不可分:宿主要区分用户取消就必须给取消一个 专属 cause(推荐 contract.ErrUserCancelled)。
func (Outcome) Status ¶
Status 该结论对应的缺省收尾目标状态(contract 词表)。
行为与既有版本逐字一致(issue #237 的零值兼容要求):不注入映射的调用方 一行不改。自有词表的宿主用 StatusWith 注入 StatusOf。新增的 Takeover 臂 返回 created(与 finalize.ActionTakeover.Status() 同值,issue #355)。
func (Outcome) StatusWith ¶ added in v0.39.0
StatusWith 按注入的映射钩子取状态词;mapper 为 nil 时回落 DefaultStatusOf (contract 词表)——「没注入」与「注入缺省实现」是同一个行为。
映射是逐次参数而不是全局开关:同一个进程里 contract 模型与自有模型的 宿主可以各用各的,互不污染。
type StatusOf ¶ added in v0.39.0
StatusOf 结论 → 收尾目标状态的映射钩子(issue #237)。
宿主的状态词表不归内核假定:contract 的词表只是**缺省**,使用自有状态机 (不 import contract、或状态名不同)的宿主可注入自己的映射,不必先把 Outcome 转成 contract 的状态常量再自映射。返回空串 = 该结论不写状态 (与缺省映射对 None / Shutdown 的处理同一口径)。
type Store ¶
type Store interface {
// LoadAnchor 读锚点;**未写必须返回 (nil, nil)**。
// 返回零值锚点会被判成「已写但过期」,续跑轮会当场 timed_out。
LoadAnchor(ctx context.Context) (*Anchor, error)
// SaveAnchor 写锚点。只在该写时被 Persist 调用一次(首轮认领成功后)。
SaveAnchor(ctx context.Context, a Anchor) error
}
Store 锚点持久化接缝(注入):首轮写一次、续跑轮读。
内核不关心存哪(DB 列 / 内存表 / 文件)、也不关心键怎么来——宿主按会话 构造实例。实现**并发安全**(收尾与恢复路径可能同时读)。