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):与用户取消、进程停机三分;
- **过期锚点立即收敛**:认领排队窗口把余量耗完的续跑轮,认领迁移成功后 立即按 timed_out 收敛,**不进编排**(进去了也只是白跑一段)。
时限是**会话生命周期**的轴:进程活得好好的也会到点。
三分与次序纪律(硬约束,Route 的测试钉住) ¶
原因值 结论 落什么 ErrSessionDeadline timed_out 终态(deny-by-default:超时的产出不可信) 宿主的用户取消哨兵 cancelled 终态 其余 ctx 已取消(进程停机) 不落终态 留给恢复循环/启动对账
**timed_out 臂必须先于「ctx.Err() != nil(进程停机)」臂。** 停机臂的条件是 「ctx 已取消」,而墙钟到点的 ctx 同样已取消(DeadlineExceeded)——次序写反, 每次会话超时都会被判成停机、**不落终态**,会话永久滞留 running。 这条次序由 finalize/收尾侧的路由表保证,本包的 Route 是它的内核侧判据面, 两边各写一句、各钉一条用例。
父 ctx 取消时子 ctx 的 Cause 传播父原因,故「用户取消/停机」不会被墙钟 装饰吃掉——三分的前提是三者各有自己的 cause(用户取消请用 context.WithCancelCause 表达,裸 cancel 与停机在 Cause 上不可分)。
与同域包的划界(各占一根轴,互不改判据) ¶
- **vs budget**:budget 是资源/窗口压力面(token/上下文水位);本包是 墙钟时限(时间轴、跨轮锚点)。一根轴都不沾——不碰 budget 的判据, 也不把时限塞进 budget。
- **vs drain**:drain 是**进程**生命周期的在途轮收敛(停机排水);本包是 **会话**生命周期的总时限。drain.ErrDeadline 与本包 ErrSessionDeadline 是两个 Cause,三分路由归收尾侧(Route 只认本包的哨兵)。
- **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 = errors.New("会话超过会话级时限")
ErrSessionDeadline 会话级墙钟超时的原因值(轮内 ctx 经 WithTimeoutCause 携带)。
识别一律走 errors.Is(可被宿主的包装链包裹);与 drain.ErrDeadline (停机排水超时)是**两个** Cause、两根轴,不要互相代入。
Functions ¶
func DefaultStatusOf ¶ added in v0.39.0
DefaultStatusOf 缺省映射:**消费 contract 的词表**,不另造一份。
不落终态的两档(None / Shutdown)返回空串:空串即「本轮没有终态要写」, 宿主据此跳过状态迁移,而不是写一个空状态。
独立导出是为了让宿主能「只覆盖个别档、其余仍走缺省」——在注入的 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, bool)
Begin 为本轮装饰墙钟 ctx:返回 (轮 ctx, 释放函数, expired)。
now 为当前时刻(宿主传 time.Now();判定与余量都以它为准)。
- **0=关闭直通**(Timeout<=0):原样返回 ctx,不装饰、不判锚点;
- **shared 且锚点有效**:沿用同一锚点的剩余时长——总时限不因续跑轮重置;
- **shared 且锚点已过期**:不装饰、expired=true。宿主在**认领迁移成功后** 按 OutcomeTimedOut 收敛(不进编排),见包头次序纪律;
- **首轮(锚点未写)/ 非 shared**:新开一段 Timeout。
release 非 nil 时必须 defer(释放定时器);expired=true 时 release 是空操作。
type Outcome ¶
type Outcome int
Outcome 三分路由的结论(超时 / 取消 / 停机,见包头表)。
const ( // OutcomeNone ctx 未取消(正常编排中,没有收敛动作)。 OutcomeNone Outcome = iota // OutcomeTimedOut 会话墙钟到点:落 timed_out 终态。 // // deny-by-default 家族——超时轮的产出是**没跑完**的,不可信: // 不得落 succeeded,也不得借排队续跑把死 ctx 再跑一轮。 OutcomeTimedOut // OutcomeCancelled 用户/调用方显式取消:落 cancelled 终态。 OutcomeCancelled // OutcomeShutdown 进程停机:**不落终态**(running/waiting_approval 留给 // 恢复循环/启动对账收敛),也不写失败报告——停机不是这次编排的结论。 OutcomeShutdown )
func Route ¶
Route 收尾段的三分路由(判据面;宿主的 finalize 路由表按同一形状实现)。
次序纪律(硬约束) ¶
**timed_out 臂必须排在停机臂(`ctx.Err() != nil`)之前。** 墙钟到点时 ctx 同样已取消(DeadlineExceeded),停机臂的条件对它同样成立——次序写反, 每次会话超时都会被判成停机、不落终态,会话永久滞留 running。 Route 的第一臂就是 timed_out,测试里用「已取消 + cause=ErrSessionDeadline」 的 ctx 钉住(该 ctx 同时满足停机臂的条件,走错臂当场红)。
三分的前提是三者各有自己的 cause:
- 墙钟:WithTimeoutCause(..., ErrSessionDeadline)(本包 WithCause);
- 用户取消:宿主用 context.WithCancelCause(哨兵) 表达,哨兵传进 userCancel;
- 停机:父 ctx 取消传播下来的 cause(或裸 cancel)。
userCancel 缺省(不传)时没有取消档:非本包 cause 的取消一律判停机—— 裸 cancel 与停机在 Cause 上不可分,宿主要区分就必须给取消一个专属 cause。
func (Outcome) Status ¶
Status 该结论对应的缺省终态词表值(contract 词表)。
行为与既有版本逐字一致(issue #237 的零值兼容要求):不注入映射的调用方 一行不改。自有词表的宿主用 StatusWith 注入 StatusOf。
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 列 / 内存表 / 文件)、也不关心键怎么来——宿主按会话 构造实例。实现**并发安全**(收尾与恢复路径可能同时读)。