Skip to content

Commit 7bb0eb7

Browse files
author
developerworks
committed
Refactor shutdown types into dedicated spec module
- Extract ShutdownBudget, TreeShutdownPolicy, and DEFAULT_FORCE_KILL_MARGIN_SECS from src/shutdown/stage.rs into new src/spec/shutdown.rs - Update all imports across runtime, spec, examples, and tests to reference crate::spec::shutdown - Simplify stage.rs to focus on runtime phase transitions only - Remove duplicate DEFAULT_FORCE_KILL_MARGIN_SECS and consolidate type definitions - Clean up unused re-exports in spec module hierarchy
1 parent c91fb88 commit 7bb0eb7

42 files changed

Lines changed: 846 additions & 647 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.specify/memory/constitution.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<!--
22
Sync Impact Report(同步影响报告)
3-
Version(版本) change(变化): 1.1.2 -> 1.1.3
3+
Version(版本) change(变化): 1.1.3 -> 1.1.4
44
Modified principles(已修改原则):
5-
- 原则 VI 与 Rust 项目约束澄清: 规格正文仍中文主导, `src/` 内 Rust 文档注释与行注释须英文
5+
- 原则 VI 与 Rust 项目约束: Rust 源码注释英文必须, 中文可选; 规格正文仍中文主导
66
Added sections(已新增章节):
77
- 无
88
Removed sections(已删除章节):
@@ -14,7 +14,7 @@ Templates requiring updates(需要同步的模板):
1414
- ✅ checked(已检查): .specify/templates/tasks-template.md
1515
- ✅ checked(已检查): .specify/templates/checklist-template.md
1616
- ✅ checked(已检查): .specify/templates/commands/*.md 目录不存在
17-
- ✅ checked(已检查): AGENTS.md Rust 节已同步英文源码注释义务
17+
- ✅ checked(已检查): AGENTS.md Rust 节已同步「英文必须, 中文可选」源码注释义务
1818
Follow-up TODOs(后续事项):
1919
- 若后续修改模板, 必须复述本文件原则, 不得削弱义务
2020
-->
@@ -95,14 +95,14 @@ Follow-up TODOs(后续事项):
9595
2. 句式必须符合现代汉语书面语法: 主语, 谓语, 宾语齐全; 定语位于中心语前; 状语位于谓语前; 补语位于谓语后. 禁止使用片段式列表冒充句子.
9696
3. 禁止非中文主导叙述, 生僻词与方言化表达.
9797
4. 英文或缩写首次出现在正文时, 必须写作 `English(中文说明)`. 后续同一概念优先继续带中文说明, 避免全英文堆叠.
98-
5. 代码标识符, 文件路径, 命令, 包名与协议字段保持原文, 但其前后解释句仍须中文; **例外**: `src/` 与测试目标内 Rust 行注释与文档注释(`//`, `///`, `//!`, 含 doctest 说明句)必须英文, 以便与工具链与跨团队审阅一致.
98+
5. 代码标识符, 文件路径, 命令, 包名与协议字段保持原文, 但其前后解释句仍须中文; **例外**: `src/`, `examples/` 与测试目标内 Rust 行注释与文档注释(`//`, `///`, `//!`, 含 doctest 说明句)英文必须, 中文可选: 每段连续注释至少一行英文, 可另起中文补充行, 禁止仅中文注释.
9999
6. 除非用户明确要求记忆, 代理与工作流禁止写入持久化"记忆".
100100

101101
**理由**: 文档读者以中文为主, 术语必须在首次出现时自解释.
102102

103103
## Rust(编程语言) 项目约束
104104

105-
1. `src/` 与被 `Cargo.toml` 注册的集成测试中的 Rust 注释与文档注释必须使用英文; 规格与手册保持原则 VI 的中文写作规则.
105+
1. `src/`, `examples/` 与被 `Cargo.toml` 注册的集成测试中的 Rust 注释与文档注释英文必须, 中文可选; 规格与手册保持原则 VI 的中文写作规则.
106106
2. 语言版本以根目录 `Cargo.toml` 中 `edition` 与工具链声明为准; 本仓库目标为 Rust 2024(编程语言版本) 生态实践.
107107
3. 格式化与静态检查必须通过 Cargo(构建工具) 官方或项目约定的子命令完成; 具体命令以 `README` 或 CI(持续集成) 为准, 本文件不锁死子命令名.
108108
4. 运行时代码必须优先使用显式类型, 窄可见性与明确 `Result`(结果类型) 边界; 禁止以全局可变状态或临时字符串拼接顶替领域模型.

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
## Rust 相关
2929

3030
- 禁止重新导出
31-
- `src/` 与测试包中的 Rust 源码必须使用英文撰写行注释与文档注释, 含 `//`, `///`, `//!`, 模块与字段文档, 以及 doctest 中的说明性句子; 本条规定优先于面向自然语言的对话术语规则, 仅约束源码注释语言, 不约束仓库内规格与 Markdown 正文的语言选择
31+
- `src/`、`examples/` 与测试包中的 Rust 行注释与文档注释(`//`, `///`, `//!`, 含 doctest 说明句)英文必须, 中文可选: 每一段连续注释至少一行含英文字母, 可另起一行中文补充; 禁止仅中文注释; 本条规定优先于对话术语规则, 不约束规格与 Markdown 正文
3232
- 代码注释必须要有
3333
- 模块注释
3434
- 结构体注释

‎examples/child_spec_builder.rs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@
88
use rust_supervisor::error::types::SupervisorError;
99
use rust_supervisor::id::types::ChildId;
1010
use rust_supervisor::policy::task_role_defaults::{SidecarConfig, TaskRole};
11-
use rust_supervisor::spec::child::{Criticality, RestartPolicy, ShutdownPolicy, TaskKind};
11+
use rust_supervisor::spec::child::{Criticality, RestartPolicy, TaskKind};
12+
use rust_supervisor::spec::shutdown::ShutdownBudget;
1213
use rust_supervisor::spec::child_builder::ChildSpecBuilder;
1314
use rust_supervisor::task::factory::{TaskResult, service_fn};
1415
use std::sync::Arc;
@@ -52,7 +53,7 @@ fn demo_worker_builder() -> Result<(), SupervisorError> {
5253
.tag("worker")
5354
.tag("invoice")
5455
.group("billing")
55-
.shutdown_policy(ShutdownPolicy::new(
56+
.shutdown_budget(ShutdownBudget::new(
5657
Duration::from_millis(150),
5758
Duration::from_millis(50),
5859
))

‎examples/job/job_task.rs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ use rust_supervisor::id::types::ChildId;
77
// Import job task role defaults.
88
use rust_supervisor::policy::task_role_defaults::TaskRole;
99
// Import child specification values.
10-
use rust_supervisor::spec::child::{ChildSpec, Criticality, ShutdownPolicy, TaskKind};
10+
use rust_supervisor::spec::child::{ChildSpec, Criticality, TaskKind};
11+
use rust_supervisor::spec::shutdown::ShutdownBudget;
1112
// Import task context values.
1213
use rust_supervisor::task::context::TaskContext;
1314
// Import task factory helpers.
@@ -74,8 +75,8 @@ pub fn job_child(events: mpsc::UnboundedSender<JobEvent>) -> Result<ChildSpec, S
7475
// Add stable diagnostic tags.
7576
child.tags = vec!["job".to_owned(), "report".to_owned()];
7677
// Use short child shutdown budgets for a fast example.
77-
child.shutdown_policy =
78-
ShutdownPolicy::new(Duration::from_millis(150), Duration::from_millis(50));
78+
child.shutdown_budget =
79+
ShutdownBudget::new(Duration::from_millis(150), Duration::from_millis(50));
7980
// Return the job child declaration.
8081
Ok(child)
8182
}

‎examples/job/main.rs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ use rust_supervisor::runtime::supervisor::Supervisor;
1010
// Import supervisor specification values.
1111
use rust_supervisor::spec::supervisor::SupervisorSpec;
1212
// Import shutdown timing policy.
13-
use rust_supervisor::shutdown::stage::ShutdownPolicy;
13+
use rust_supervisor::spec::shutdown::{ShutdownBudget, TreeShutdownPolicy};
1414
// Import duration values for the example timing budget.
1515
use std::time::Duration;
1616
// Import asynchronous channel helpers.
@@ -33,15 +33,15 @@ async fn main() -> ExampleResult {
3333
// Keep enough event buffer for the shutdown observation sequence.
3434
spec.event_channel_capacity = 32;
3535
// Use short shutdown windows so the cleanup path finishes quickly.
36-
let shutdown_policy = ShutdownPolicy::new(
37-
Duration::from_millis(250),
38-
Duration::from_millis(50),
36+
spec.tree_shutdown = TreeShutdownPolicy::new(
37+
ShutdownBudget::new(Duration::from_millis(250), Duration::from_millis(50)),
3938
true,
4039
Duration::from_millis(250),
4140
3,
4241
);
42+
spec.propagate_tree_shutdown_budget();
4343
// Start the runtime with the job child.
44-
let handle = Supervisor::start_with_policy(spec, shutdown_policy).await?;
44+
let handle = Supervisor::start(spec).await?;
4545
// Subscribe to lifecycle event text before commands are sent.
4646
let mut runtime_events = handle.subscribe_events();
4747
// Wait until the job reports initialization.

‎examples/service/main.rs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ use rust_supervisor::runtime::supervisor::Supervisor;
1313
// Import supervisor specification values.
1414
use rust_supervisor::spec::supervisor::SupervisorSpec;
1515
// Import shutdown timing policy.
16-
use rust_supervisor::shutdown::stage::ShutdownPolicy;
16+
use rust_supervisor::spec::shutdown::{ShutdownBudget, TreeShutdownPolicy};
1717
// Import duration values for the example timing budget.
1818
use std::time::Duration;
1919
// Import asynchronous channel helpers.
@@ -36,15 +36,15 @@ async fn main() -> ExampleResult {
3636
// Keep enough event buffer for the full shutdown observation sequence.
3737
spec.event_channel_capacity = 32;
3838
// Use short shutdown windows so the example finishes quickly.
39-
let shutdown_policy = ShutdownPolicy::new(
40-
Duration::from_millis(250),
41-
Duration::from_millis(50),
39+
spec.tree_shutdown = TreeShutdownPolicy::new(
40+
ShutdownBudget::new(Duration::from_millis(250), Duration::from_millis(50)),
4241
true,
4342
Duration::from_millis(250),
4443
3,
4544
);
45+
spec.propagate_tree_shutdown_budget();
4646
// Start the runtime with the service child.
47-
let handle = Supervisor::start_with_policy(spec, shutdown_policy).await?;
47+
let handle = Supervisor::start(spec).await?;
4848
// Subscribe to lifecycle event text before commands are sent.
4949
let mut runtime_events = handle.subscribe_events();
5050
// Wait until the service reports initialization.

‎examples/service/service_task.rs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ use rust_supervisor::id::types::ChildId;
77
// Import service task role defaults.
88
use rust_supervisor::policy::task_role_defaults::TaskRole;
99
// Import child specification values.
10-
use rust_supervisor::spec::child::{ChildSpec, Criticality, ShutdownPolicy, TaskKind};
10+
use rust_supervisor::spec::child::{ChildSpec, Criticality, TaskKind};
11+
use rust_supervisor::spec::shutdown::ShutdownBudget;
1112
// Import task context values.
1213
use rust_supervisor::task::context::TaskContext;
1314
// Import task factory helpers.
@@ -80,8 +81,8 @@ pub fn service_child(
8081
// Add stable diagnostic tags.
8182
child.tags = vec!["service".to_owned(), "quotes".to_owned()];
8283
// Use short child shutdown budgets for a fast example.
83-
child.shutdown_policy =
84-
ShutdownPolicy::new(Duration::from_millis(150), Duration::from_millis(50));
84+
child.shutdown_budget =
85+
ShutdownBudget::new(Duration::from_millis(150), Duration::from_millis(50));
8586
// Return the service child declaration.
8687
Ok(child)
8788
}

‎examples/shutdown_pipeline_demo.rs‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@ use rust_supervisor::shutdown::report::{
1616
ChildShutdownOutcome, ChildShutdownOutcomeInput, ChildShutdownStatus, ResourceReconcileStatus,
1717
ShutdownPipelineReport, ShutdownReconcileReport,
1818
};
19-
use rust_supervisor::shutdown::stage::{ShutdownCause, ShutdownPhase, ShutdownPolicy};
19+
use rust_supervisor::shutdown::stage::{ShutdownCause, ShutdownPhase};
20+
use rust_supervisor::spec::shutdown::{ShutdownBudget, TreeShutdownPolicy};
2021
use std::time::Duration;
2122

2223
/// Runs the shutdown pipeline demonstration.
@@ -29,20 +30,25 @@ fn main() {
2930
println!();
3031

3132
// Build the sample shutdown policy.
32-
let policy = ShutdownPolicy::new(
33-
Duration::from_secs(5), // graceful_timeout
34-
Duration::from_secs(1), // abort_wait
33+
let policy = TreeShutdownPolicy::new(
34+
ShutdownBudget::new(
35+
Duration::from_secs(5), // graceful_timeout
36+
Duration::from_secs(1), // abort_wait
37+
),
3538
true, // abort_after_timeout
3639
Duration::from_secs(5), // force_kill_margin
3740
3, // max_orphan_threshold
3841
);
3942

4043
// Print the shutdown policy values.
41-
println!(" graceful_timeout = {:?}", policy.graceful_timeout);
42-
println!(" abort_wait = {:?}", policy.abort_wait);
44+
println!(
45+
" graceful_timeout = {:?}",
46+
policy.budget.graceful_timeout
47+
);
48+
println!(" abort_wait = {:?}", policy.budget.abort_wait);
4349
println!(
4450
" interpretation: wait {:?} for cooperative stop, then {:?} for abort",
45-
policy.graceful_timeout, policy.abort_wait,
51+
policy.budget.graceful_timeout, policy.budget.abort_wait,
4652
);
4753

4854
// --- Shutdown Phases ---
@@ -92,9 +98,8 @@ fn main() {
9298
println!();
9399

94100
// Build a coordinator-specific policy.
95-
let coord_policy = ShutdownPolicy::new(
96-
Duration::from_secs(5),
97-
Duration::from_secs(1),
101+
let coord_policy = TreeShutdownPolicy::new(
102+
ShutdownBudget::new(Duration::from_secs(5), Duration::from_secs(1)),
98103
true,
99104
Duration::from_secs(5),
100105
3,

‎examples/sidecar/main.rs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ use rust_supervisor::runtime::supervisor::Supervisor;
1212
// Import supervisor specification values.
1313
use rust_supervisor::spec::supervisor::SupervisorSpec;
1414
// Import shutdown timing policy.
15-
use rust_supervisor::shutdown::stage::ShutdownPolicy;
15+
use rust_supervisor::spec::shutdown::{ShutdownBudget, TreeShutdownPolicy};
1616
// Import duration values for the example timing budget.
1717
use std::time::Duration;
1818
// Import asynchronous channel helpers.
@@ -37,15 +37,15 @@ async fn main() -> ExampleResult {
3737
// Keep enough event buffer for the full shutdown observation sequence.
3838
spec.event_channel_capacity = 64;
3939
// Use short shutdown windows so the example finishes quickly.
40-
let shutdown_policy = ShutdownPolicy::new(
41-
Duration::from_millis(250),
42-
Duration::from_millis(50),
40+
spec.tree_shutdown = TreeShutdownPolicy::new(
41+
ShutdownBudget::new(Duration::from_millis(250), Duration::from_millis(50)),
4342
true,
4443
Duration::from_millis(250),
4544
3,
4645
);
46+
spec.propagate_tree_shutdown_budget();
4747
// Start the runtime with the primary service and sidecar.
48-
let handle = Supervisor::start_with_policy(spec, shutdown_policy).await?;
48+
let handle = Supervisor::start(spec).await?;
4949
// Subscribe to lifecycle event text before commands are sent.
5050
let mut runtime_events = handle.subscribe_events();
5151
// Wait until both children report initialization.

‎examples/sidecar/sidecar_task.rs‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ use rust_supervisor::id::types::ChildId;
77
// Import task role defaults and sidecar configuration.
88
use rust_supervisor::policy::task_role_defaults::{SidecarConfig, TaskRole};
99
// Import child specification values.
10-
use rust_supervisor::spec::child::{ChildSpec, Criticality, ShutdownPolicy, TaskKind};
10+
use rust_supervisor::spec::child::{ChildSpec, Criticality, TaskKind};
11+
use rust_supervisor::spec::shutdown::ShutdownBudget;
1112
// Import task context values.
1213
use rust_supervisor::task::context::TaskContext;
1314
// Import task factory helpers.
@@ -84,8 +85,8 @@ pub fn primary_service_child(
8485
// Add stable diagnostic tags.
8586
child.tags = vec!["service".to_owned(), "api".to_owned()];
8687
// Use short child shutdown budgets for a fast example.
87-
child.shutdown_policy =
88-
ShutdownPolicy::new(Duration::from_millis(150), Duration::from_millis(50));
88+
child.shutdown_budget =
89+
ShutdownBudget::new(Duration::from_millis(150), Duration::from_millis(50));
8990
// Return the primary child declaration.
9091
Ok(child)
9192
}
@@ -131,8 +132,8 @@ pub fn sidecar_child(
131132
// Add stable diagnostic tags.
132133
child.tags = vec!["sidecar".to_owned(), "metrics".to_owned()];
133134
// Use short child shutdown budgets for a fast example.
134-
child.shutdown_policy =
135-
ShutdownPolicy::new(Duration::from_millis(150), Duration::from_millis(50));
135+
child.shutdown_budget =
136+
ShutdownBudget::new(Duration::from_millis(150), Duration::from_millis(50));
136137
// Return the sidecar child declaration.
137138
Ok(child)
138139
}

0 commit comments

Comments
 (0)