flare_core_runtime/task/
trait.rs

1//! Task trait 定义
2//!
3//! 任务抽象是运行时的核心扩展点，所有需要在运行时中管理的任务都必须实现此 trait
4
5use super::state::TaskState;
6use std::future::Future;
7use std::pin::Pin;
8
9/// 任务执行结果
10pub type TaskResult = Result<(), Box<dyn std::error::Error + Send + Sync>>;
11
12/// 任务抽象 (核心扩展点)
13///
14/// 所有需要在运行时中管理的任务都必须实现此 trait
15/// 支持依赖声明、生命周期钩子、就绪检查
16///
17/// # 实现说明
18///
19/// - 使用 Rust 2024 原生 async fn in traits（不使用 async-trait 宏）
20/// - 所有方法提供默认实现，降低实现难度
21/// - 支持依赖管理、优先级、关键任务标记
22///
23/// # 示例
24///
25/// ```rust
26/// use flare_core_runtime::task::{Task, TaskResult};
27/// use std::pin::Pin;
28/// use std::future::Future;
29///
30/// struct MyTask {
31///     name: String,
32/// }
33///
34/// impl Task for MyTask {
35///     fn name(&self) -> &str {
36///         &self.name
37///     }
38///
39///     fn run(
40///         self: Box<Self>,
41///         shutdown_rx: tokio::sync::oneshot::Receiver<()>,
42///     ) -> Pin<Box<dyn Future<Output = TaskResult> + Send>> {
43///         Box::pin(async move {
44///             // 任务逻辑
45///             Ok(())
46///         })
47///     }
48/// }
49/// ```
50pub trait Task: Send {
51    /// 获取任务名称
52    ///
53    /// 任务名称必须唯一，用于日志、指标和依赖管理
54    fn name(&self) -> &str;
55
56    /// 获取任务依赖
57    ///
58    /// 返回此任务依赖的其他任务名称列表
59    /// 依赖的任务会在此任务之前启动
60    ///
61    /// # 默认实现
62    ///
63    /// 返回空列表（无依赖）
64    fn dependencies(&self) -> Vec<String> {
65        Vec::new()
66    }
67
68    /// 运行任务
69    ///
70    /// # 参数
71    ///
72    /// * `shutdown_rx` - 关闭信号接收器，当收到信号时任务应该优雅关闭
73    ///
74    /// # 返回
75    ///
76    /// 返回一个 Future，执行任务逻辑
77    ///
78    /// # 实现要求
79    ///
80    /// - 必须响应 shutdown_rx 信号，实现优雅停机
81    /// - 错误时返回 `Err`，运行时会根据 `is_critical()` 决定是否停机
82    fn run(
83        self: Box<Self>,
84        shutdown_rx: tokio::sync::oneshot::Receiver<()>,
85    ) -> Pin<Box<dyn Future<Output = TaskResult> + Send>>;
86
87    /// 就绪检查 (可选)
88    ///
89    /// 用于检查任务是否已经就绪（例如 gRPC 服务是否已经可以接受连接）
90    ///
91    /// # 默认实现
92    ///
93    /// 总是返回成功
94    fn ready_check(&self) -> Pin<Box<dyn Future<Output = TaskResult> + Send + '_>> {
95        Box::pin(async { Ok(()) })
96    }
97
98    /// 任务优先级 (用于启动顺序调整)
99    ///
100    /// 优先级高的任务先启动（在依赖关系满足的前提下）
101    ///
102    /// # 默认实现
103    ///
104    /// 返回 0（中等优先级）
105    fn priority(&self) -> i32 {
106        0
107    }
108
109    /// 是否关键任务 (失败时触发运行时停机)
110    ///
111    /// # 默认实现
112    ///
113    /// 返回 false（非关键任务）
114    fn is_critical(&self) -> bool {
115        false
116    }
117
118    /// 获取初始状态
119    ///
120    /// # 默认实现
121    ///
122    /// 返回 `TaskState::Pending`
123    fn initial_state(&self) -> TaskState {
124        TaskState::Pending
125    }
126}
flare_core_runtime/task/trait.rs

flare_core_runtime/task/
trait.rs
