From b370dea36817f3f4273f7f8281ce6843adef276d Mon Sep 17 00:00:00 2001 From: ApsisRS contributors Date: Fri, 2 Oct 2026 01:01:36 +0800 Subject: [PATCH] docs: bilingual comments for apsis-task --- crates/ops/apsis-task/src/error.rs | 8 +- crates/ops/apsis-task/src/precedence.rs | 59 ++++++++ crates/ops/apsis-task/src/task.rs | 178 ++++++++++++++++++++++++ 3 files changed, 241 insertions(+), 4 deletions(-) diff --git a/crates/ops/apsis-task/src/error.rs b/crates/ops/apsis-task/src/error.rs index d8117aa..18b3ddd 100644 --- a/crates/ops/apsis-task/src/error.rs +++ b/crates/ops/apsis-task/src/error.rs @@ -3,8 +3,8 @@ use core::fmt; /// The category of a task error. - /// - /// 任务错误的类别。 +/// +/// 任务错误的类别。 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[non_exhaustive] pub enum TaskErrorKind { @@ -64,8 +64,8 @@ impl fmt::Display for TaskErrorKind { } /// A failure while building or querying a task. - /// - /// 构建或查询任务时发生的失败。 +/// +/// 构建或查询任务时发生的失败。 #[derive(Debug, Clone, PartialEq, Eq)] pub struct TaskError { kind: TaskErrorKind, diff --git a/crates/ops/apsis-task/src/precedence.rs b/crates/ops/apsis-task/src/precedence.rs index 4cf594f..d4de39f 100644 --- a/crates/ops/apsis-task/src/precedence.rs +++ b/crates/ops/apsis-task/src/precedence.rs @@ -24,16 +24,27 @@ use std::collections::BTreeMap; /// An edge from one task to another means the first must finish before the /// second starts. The order of the tasks themselves is the caller's: the /// graph only records which pairs are related. +/// +/// 优先约束构成的有向无环图。 +/// +/// 从一个任务指向另一个任务的边表示前者必须先于后者完成。任务本身的次序 +/// 由调用方决定：该图只记录哪些任务对之间存在关系。 #[derive(Debug, Clone, PartialEq, Default)] pub struct PrecedenceGraph { /// The successors of each task, in the order the edges were added. + /// + /// 各任务的后继，按边添加顺序排列。 successors: BTreeMap>, /// The predecessors of each task, in the order the edges were added. + /// + /// 各任务的前驱，按边添加顺序排列。 predecessors: BTreeMap>, } impl PrecedenceGraph { /// Creates an empty graph. + /// + /// 创建一个空图。 pub fn new() -> Self { Self { successors: BTreeMap::new(), @@ -42,16 +53,22 @@ impl PrecedenceGraph { } /// Returns the number of edges. + /// + /// 返回边的数量。 pub fn edge_count(&self) -> usize { self.successors.values().map(Vec::len).sum() } /// Returns `true` when there are no edges. + /// + /// 当没有边时返回 `true`。 pub fn is_empty(&self) -> bool { self.successors.values().all(Vec::is_empty) } /// Returns `true` when the constraint from `before` to `after` exists. + /// + /// 当存在从 `before` 到 `after` 的约束时返回 `true`。 pub fn has_constraint(&self, before: TaskId, after: TaskId) -> bool { self.successors .get(&before.index()) @@ -66,6 +83,14 @@ impl PrecedenceGraph { /// Adding a constraint that already exists is accepted and has no effect, /// so a caller may assemble a graph from overlapping sources without /// having to deduplicate. + /// + /// 添加一条约束：`before` 必须在 `after` 开始之前完成。 + /// + /// 两个标识符相同时返回错误，因为任务不能先于自身；该约束会闭成环时 + /// 亦返回错误。 + /// + /// 添加已存在的约束被接受且不起作用，故调用方可以从多个有重叠的数据源 + /// 汇集一个图，无须先去重。 pub fn add(&mut self, before: TaskId, after: TaskId) -> Result<(), TaskError> { if before == after { return Err(TaskError::new(TaskErrorKind::PrecedenceCycle) @@ -78,6 +103,8 @@ impl PrecedenceGraph { // `before` is already reachable from `after`. That is checked before // the edge is inserted, so a rejected edge leaves the graph // unchanged. + // 从 `before` 到 `after` 的新边恰在 `before` 已可自 `after` 到达时 + // 闭成环。该检查先于插入，故被拒的边不会改变图。 if self.is_reachable(after, before) { return Err( TaskError::new(TaskErrorKind::PrecedenceCycle).with_detail(format!( @@ -98,6 +125,8 @@ impl PrecedenceGraph { /// Returns `true` when `to` is reachable from `from` following the /// constraints. + /// + /// 当沿约束可自 `from` 到达 `to` 时返回 `true`。 pub fn is_reachable(&self, from: TaskId, to: TaskId) -> bool { if from == to { return true; @@ -123,6 +152,10 @@ impl PrecedenceGraph { /// /// The result is in the order the constraints were added. It is the /// direct predecessors only, not the transitive closure. + /// + /// 返回必须在某任务开始前完成的任务。 + /// + /// 结果按约束添加顺序排列。它只含直接前驱，不含传递闭包。 pub fn predecessors_of(&self, task: TaskId) -> Vec { self.predecessors .get(&task.index()) @@ -134,6 +167,10 @@ impl PrecedenceGraph { /// /// The result is in the order the constraints were added. It is the /// direct successors only, not the transitive closure. + /// + /// 返回必须等待某任务完成的任务。 + /// + /// 结果按约束添加顺序排列。它只含直接后继，不含传递闭包。 pub fn successors_of(&self, task: TaskId) -> Vec { self.successors .get(&task.index()) @@ -142,9 +179,12 @@ impl PrecedenceGraph { } /// Returns the tasks with no predecessor. + /// + /// 返回没有前驱的任务。 pub fn roots(&self) -> Vec { // Every task that appears as a successor has a predecessor, so the // roots are the tasks that appear only as a predecessor. + // 凡出现为后继的任务都有前驱，故根是那些只作为前驱出现的任务。 let mut roots: Vec = Vec::new(); for task in self.successors.keys() { if !self.predecessors.contains_key(task) && !roots.contains(task) { @@ -156,6 +196,8 @@ impl PrecedenceGraph { } /// Returns the tasks with no successor. + /// + /// 返回没有后继的任务。 pub fn leaves(&self) -> Vec { let mut leaves: Vec = Vec::new(); for task in self.predecessors.keys() { @@ -182,8 +224,20 @@ impl PrecedenceGraph { /// tasks. The graph rejects cycles as they are added, so this can only /// happen when a caller builds the graph from one task set and orders /// another, or when the tasks are not all in the graph. + /// + /// 返回所给任务的拓扑序。 + /// + /// 该次序满足每一条约束：任务出现在其所有前驱之后。平局按该任务在所给 + /// 列表中的位置打破，使调用方可在本来无序的任务间表达自己的偏好。这 + /// 正是让规划器在约束允许的自由度内先放置更有价值的任务。 + /// + /// 列表中无任何约束的任务同样出现。 + /// + /// 当图在所给任务之间含环时返回错误。该图在添加时就拒绝成环，故这只 + /// 可能发生在调用方以一组任务建图却对另一组排序，或任务未全在图中时。 pub fn topological_order(&self, tasks: &[TaskId]) -> Result, TaskError> { // The position of each task in the supplied list, which breaks ties. + // 各任务在所给列表中的位置，用于打破平局。 let mut preference: BTreeMap = BTreeMap::new(); for (position, task) in tasks.iter().enumerate() { preference.insert(task.index(), position); @@ -192,6 +246,8 @@ impl PrecedenceGraph { // The number of predecessors of each task that are themselves in the // list. A predecessor outside the list is ignored, because it cannot // be scheduled and so cannot be waited for. + // 各任务在列表内的前驱个数。列表外的前驱被忽略，因为它无法被 + // 调度，也就无从等待。 let mut pending: BTreeMap = BTreeMap::new(); for task in tasks { let count = self @@ -208,6 +264,7 @@ impl PrecedenceGraph { while order.len() < tasks.len() { // Among the tasks whose predecessors are all placed, take the // one the caller prefers. + // 在前驱均已放置的任务中，取调用方偏好者。 let next = tasks .iter() .map(|task| task.index()) @@ -233,6 +290,8 @@ impl PrecedenceGraph { } /// Returns the number of tasks in the graph. + /// + /// 返回图中的任务数。 pub fn task_count(&self) -> usize { let mut all: Vec = self.successors.keys().copied().collect(); for task in self.predecessors.keys() { diff --git a/crates/ops/apsis-task/src/task.rs b/crates/ops/apsis-task/src/task.rs index a10af80..ebd65b2 100644 --- a/crates/ops/apsis-task/src/task.rs +++ b/crates/ops/apsis-task/src/task.rs @@ -4,16 +4,22 @@ use crate::error::{TaskError, TaskErrorKind}; use apsis_resource::ResourceId; /// An identifier for a task. +/// +/// 任务的标识符。 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] pub struct TaskId(pub usize); impl TaskId { /// Creates an identifier. + /// + /// 创建一个标识符。 pub const fn new(index: usize) -> Self { Self(index) } /// Returns the index. + /// + /// 返回该下标。 pub const fn index(self) -> usize { self.0 } @@ -31,21 +37,34 @@ impl core::fmt::Display for TaskId { /// while it runs. A demand that exceeds the resource's capacity makes the /// task impossible to schedule there, which a scheduler discovers by /// comparing the two. +/// +/// 任务对某个资源的需求。 +/// +/// 需求是任务运行期间消耗的资源容量大小。超出资源容量的需求使该任务无法在 +/// 此处调度，调度器通过比较二者即可发现。 #[derive(Debug, Clone, Copy, PartialEq)] pub struct Requirement { /// The resource required. + /// + /// 所要求的资源。 pub resource: ResourceId, /// The amount of the resource consumed. + /// + /// 消耗的资源量。 pub demand: f64, } impl Requirement { /// Creates a requirement. + /// + /// 创建一条需求。 pub const fn new(resource: ResourceId, demand: f64) -> Self { Self { resource, demand } } /// Returns `true` when the demand is positive and finite. + /// + /// 当该需求为正且有限时返回 `true`。 pub fn is_valid(&self) -> bool { self.demand.is_finite() && self.demand > 0.0 } @@ -56,35 +75,65 @@ impl Requirement { /// A task is immutable after construction. The builder methods take `self` by /// value and return a new task, so a caller can share a base task and derive /// variants from it without the variants interfering. +/// +/// 待调度的一份工作。 +/// +/// 任务在构造后不可变。各构建方法按值接收 `self` 并返回新任务，故调用方 +/// 可以共享一个基础任务并由它派生出若干变体，而变体之间互不干扰。 #[derive(Debug, Clone, PartialEq)] pub struct Task { /// The identifier of this task. + /// + /// 该任务的标识符。 pub id: TaskId, /// The duration of the task, in seconds. + /// + /// 任务时长，单位为秒。 pub duration: f64, /// The earliest time at which the task may start, in seconds. /// /// This is the start of the earliest window in which the task may run. /// A task with no window has no restriction, which is what the /// constructors give. + /// + /// 该任务可开始的最早时刻，单位为秒。 + /// + /// 即该任务可运行的最早窗口的起点。没有窗口的任务不受限制，构造函数 + /// 给出的正是这种情形。 pub earliest_start: f64, /// The latest time at which the task may end, in seconds. /// /// A task with no window has no restriction. + /// + /// 该任务可结束的最晚时刻，单位为秒。 + /// + /// 没有窗口的任务不受限制。 pub latest_end: f64, /// The resources the task requires, in the order they were added. + /// + /// 该任务要求的资源，按添加顺序排列。 pub requirements: Vec, /// The priority of the task. /// /// A larger value means the task is more important. The scale is the /// caller's. A scheduler that maximises weighted value uses this number, /// and one that maximises the count of scheduled tasks ignores it. + /// + /// 该任务的优先级。 + /// + /// 值越大表示任务越重要，量纲由调用方确定。最大化加权价值的调度器使用 + /// 该数值，而最大化已调度任务数的调度器则忽略它。 pub priority: f64, /// Whether the task must be scheduled. /// /// A mandatory task is scheduled even at the cost of other tasks. A /// scheduler may still fail to place one when no placement exists, and /// reports that rather than dropping it silently. + /// + /// 该任务是否必须被调度。 + /// + /// 强制任务即使以牺牲其他任务为代价也要调度。当不存在可行放置时调度器 + /// 仍可能无法安排它，此时会报告，而不是静默丢弃。 pub mandatory: bool, } @@ -93,6 +142,10 @@ impl Task { /// /// The task may start at any finite time, because it has no window. It /// has a priority of zero and is not mandatory. + /// + /// 以给定时长、无资源需求创建任务。 + /// + /// 该任务没有窗口，故可在任意有限时刻开始。其优先级为零，且非强制。 pub fn new(id: TaskId, duration: f64) -> Self { Self { id, @@ -110,6 +163,11 @@ impl Task { /// The window is the interval in which the whole task must fit, so the /// task may start no earlier than the window start and must end no later /// than the window end. + /// + /// 返回带时间窗口的本任务副本。 + /// + /// 该窗口是整个任务必须容纳其中的区间，故任务起点不早于窗口起点、终点 + /// 不晚于窗口终点。 pub fn with_window(mut self, start: f64, end: f64) -> Self { self.earliest_start = start; self.latest_end = end; @@ -117,12 +175,16 @@ impl Task { } /// Returns a copy of this task with a priority. + /// + /// 返回带给定优先级的本任务副本。 pub fn with_priority(mut self, priority: f64) -> Self { self.priority = priority; self } /// Returns a copy of this task marked mandatory or not. + /// + /// 返回标记为强制或非强制的本任务副本。 pub fn with_mandatory(mut self, mandatory: bool) -> Self { self.mandatory = mandatory; self @@ -133,6 +195,11 @@ impl Task { /// Adding the same resource twice is allowed at this point, because a /// builder chain cannot report an error. [`Task::validate`] rejects it, /// and [`Task::try_require`] reports it immediately. + /// + /// 返回附加一条资源需求的本任务副本。 + /// + /// 此处允许重复加入同一资源，因为构建者链无法报告错误。 + /// [`Task::validate`] 会拒绝它，[`Task::try_require`] 则立即报告。 pub fn require(mut self, resource: ResourceId, demand: f64) -> Self { self.requirements.push(Requirement::new(resource, demand)); self @@ -140,6 +207,8 @@ impl Task { /// Returns a copy of this task with an additional resource requirement, /// reporting a duplicate or an invalid demand immediately. + /// + /// 返回附加一条资源需求的本任务副本，并立即报告重复或无效需求。 pub fn try_require(mut self, resource: ResourceId, demand: f64) -> Result { let requirement = Requirement::new(resource, demand); if !requirement.is_valid() { @@ -161,6 +230,10 @@ impl Task { /// Returns the demand the task makes on a resource. /// /// Returns `None` when the task does not require the resource. + /// + /// 返回该任务对某资源的需求。 + /// + /// 该任务不要求该资源时返回 `None`。 pub fn demand_for(&self, resource: ResourceId) -> Option { self.requirements .iter() @@ -169,16 +242,22 @@ impl Task { } /// Returns `true` when the task requires a resource. + /// + /// 当该任务要求某资源时返回 `true`。 pub fn requires(&self, resource: ResourceId) -> bool { self.demand_for(resource).is_some() } /// Returns the number of resources the task requires. + /// + /// 返回该任务要求的资源数量。 pub fn requirement_count(&self) -> usize { self.requirements.len() } /// Returns the identifiers of the required resources. + /// + /// 返回所要求资源的标识符。 pub fn resources(&self) -> Vec { self.requirements .iter() @@ -191,11 +270,17 @@ impl Task { /// /// Returns infinity when the task has no restriction at either end, and /// zero or a negative value when the window cannot hold the task at all. + /// + /// 返回该任务必须容纳其中的窗口长度，单位为秒。 + /// + /// 任务两端均无限制时返回无穷；窗口完全容不下该任务时返回零或负值。 pub fn window_length(&self) -> f64 { self.latest_end - self.earliest_start } /// Returns `true` when the window cannot hold the task. + /// + /// 当窗口容不下该任务时返回 `true`。 pub fn window_is_too_short(&self) -> bool { self.duration > self.window_length() } @@ -204,17 +289,25 @@ impl Task { /// /// Returns infinity when the task has no upper bound, and negative /// infinity when it has no lower bound. + /// + /// 返回在其窗口下该任务可能结束的最早时刻。 + /// + /// 任务无上界时返回无穷，无下界时返回负无穷。 pub fn earliest_possible_end(&self) -> f64 { self.earliest_start + self.duration } /// Returns `true` when the task fits its window. + /// + /// 当该任务能容纳于其窗口时返回 `true`。 pub fn fits_window(&self) -> bool { !self.window_is_too_short() } /// Returns `true` when the task uses any resource more than once, or /// demands a non-positive amount. + /// + /// 当该任务重复使用某资源，或需求非正时返回 `true`。 pub fn has_duplicate_requirements(&self) -> bool { self.requirements .iter() @@ -232,6 +325,11 @@ impl Task { /// is finite at the ends it states and holds the duration, every demand /// is positive and finite and names a distinct resource, and the weights /// are finite. + /// + /// 校验该任务；不可用时返回原因。 + /// + /// 任务可用当且仅当：时长有限且为正；窗口在其给出的两端有限并容得下该 + /// 时长；每条需求为正且有限并指向互不相同的资源；各权值有限。 pub fn validate(&self) -> Result<(), TaskError> { if !self.duration.is_finite() || self.duration <= 0.0 { return Err(TaskError::new(TaskErrorKind::InvalidDuration) @@ -282,6 +380,8 @@ impl Task { } /// Returns `true` when the task is usable. + /// + /// 当该任务可用时返回 `true`。 pub fn is_valid(&self) -> bool { self.validate().is_ok() } @@ -292,6 +392,11 @@ impl Task { /// This is the quantity a scheduler maximises when it is asked to make /// the most of the available time: a long task of high priority is worth /// more than a short one of the same priority. + /// + /// 返回该任务的价值，即其优先级与时长的乘积。 + /// + /// 当调度器被要求充分利用可用时间时，最大化的正是该量：同等优先级下 + /// 时长较长的任务价值更高。 pub fn weighted_value(&self) -> f64 { self.priority * self.duration } @@ -315,38 +420,64 @@ impl core::fmt::Display for Task { /// considered for several placements without being modified. A task that has /// been placed records when and where, so that a schedule can be examined /// without a second lookup. +/// +/// 调度器为某任务指定的状态。 +/// +/// 状态与任务分开保存，故同一任务可被考虑多次放置而不被修改。已放置的 +/// 任务记录了何时何地，从而无需二次查找即可检查一份计划。 #[derive(Debug, Clone, PartialEq)] pub enum TaskState { /// The task has not been placed and is still being considered. + /// + /// 该任务尚未放置，仍在考虑之中。 Pending, /// The task has been placed at a time. + /// + /// 该任务已在某时刻放置。 Scheduled { /// The start time of the placement, in seconds. + /// + /// 放置的起始时刻，单位为秒。 start: f64, }, /// The task was deliberately left out. /// /// A scheduler reports this rather than silently dropping a task, so that /// an operator can see what was given up and why. + /// + /// 该任务被有意排除在外。 + /// + /// 调度器报告此状态而非静默丢弃任务，使操作者能看出放弃了什么以及 + /// 为什么。 Deferred, /// The task cannot be scheduled at all. /// /// A task is infeasible when its window is too short, when it demands /// more of a resource than the resource has, or when a resource it needs /// does not exist. + /// + /// 该任务完全无法调度。 + /// + /// 任务不可行的情形有：窗口过短；需求超过某资源容量；所需资源不存在。 Infeasible { /// A description of why the task cannot be scheduled. + /// + /// 该任务无法调度的原因说明。 reason: String, }, } impl TaskState { /// Returns `true` when the task has been placed. + /// + /// 当该任务已被放置时返回 `true`。 pub const fn is_scheduled(&self) -> bool { matches!(self, Self::Scheduled { .. }) } /// Returns the start time of the placement, if there is one. + /// + /// 返回放置的起始时刻，若有。 pub const fn start(&self) -> Option { match self { Self::Scheduled { start } => Some(*start), @@ -355,11 +486,15 @@ impl TaskState { } /// Returns the end time of the placement, if there is one. + /// + /// 返回放置的结束时刻，若有。 pub fn end(&self, duration: f64) -> Option { self.start().map(|start| start + duration) } /// Returns a short name for the state. + /// + /// 返回该状态的简称。 pub const fn name(&self) -> &'static str { match self { Self::Pending => "pending", @@ -371,6 +506,8 @@ impl TaskState { } /// A collection of tasks, indexed by identifier. +/// +/// 以标识符为索引的任务集合。 #[derive(Debug, Clone, PartialEq, Default)] pub struct TaskSet { tasks: Vec, @@ -378,6 +515,8 @@ pub struct TaskSet { impl TaskSet { /// Creates an empty set. + /// + /// 创建一个空集合。 pub const fn new() -> Self { Self { tasks: Vec::new() } } @@ -386,6 +525,10 @@ impl TaskSet { /// /// Returns an error when two tasks share an identifier or when any task /// is not usable. + /// + /// 由一组任务创建集合。 + /// + /// 两个任务标识符相同或任一任务不可用时返回错误。 pub fn from_tasks(tasks: Vec) -> Result { let mut set = Self::new(); for task in tasks { @@ -398,6 +541,10 @@ impl TaskSet { /// /// Returns an error when the identifier is already present or when the /// task is not usable. + /// + /// 插入一个任务。 + /// + /// 该标识符已存在或该任务不可用时返回错误。 pub fn insert(&mut self, task: Task) -> Result<(), TaskError> { task.validate()?; if self.get(task.id).is_some() { @@ -410,6 +557,8 @@ impl TaskSet { } /// Returns the task with the given identifier. + /// + /// 返回具有所给标识符的任务。 pub fn get(&self, id: TaskId) -> Option<&Task> { self.tasks.iter().find(|task| task.id == id) } @@ -417,6 +566,10 @@ impl TaskSet { /// Removes a task. /// /// Returns an error when no task has the identifier. + /// + /// 移除一个任务。 + /// + /// 没有任务具有该标识符时返回错误。 pub fn remove(&mut self, id: TaskId) -> Result { let index = self .tasks @@ -429,16 +582,22 @@ impl TaskSet { } /// Returns the tasks in the order they were added. + /// + /// 返回按添加顺序排列的任务。 pub fn tasks(&self) -> &[Task] { &self.tasks } /// Returns the number of tasks. + /// + /// 返回任务数量。 pub fn len(&self) -> usize { self.tasks.len() } /// Returns `true` when there are no tasks. + /// + /// 当没有任务时返回 `true`。 pub fn is_empty(&self) -> bool { self.tasks.is_empty() } @@ -447,16 +606,24 @@ impl TaskSet { /// /// This is the load the tasks would place on the schedule if each used /// one unit of resource for its whole duration. + /// + /// 返回所有任务的总时长，单位为秒。 + /// + /// 这是各任务在整个时长内各占一个单位资源时，会施加到计划上的负载。 pub fn total_duration(&self) -> f64 { self.tasks.iter().map(|task| task.duration).sum() } /// Returns the total weighted value of every task. + /// + /// 返回所有任务的总加权价值。 pub fn total_weighted_value(&self) -> f64 { self.tasks.iter().map(Task::weighted_value).sum() } /// Returns the identifiers of the tasks that require a resource. + /// + /// 返回要求某资源的任务标识符。 pub fn tasks_requiring(&self, resource: ResourceId) -> Vec { self.tasks .iter() @@ -466,6 +633,8 @@ impl TaskSet { } /// Returns the identifiers of the mandatory tasks. + /// + /// 返回强制任务的标识符。 pub fn mandatory(&self) -> Vec { self.tasks .iter() @@ -486,6 +655,15 @@ impl TaskSet { /// This is not guaranteed to find the best possible schedule. Scheduling /// with resource constraints is intractable in general, so a heuristic is the /// practical choice and the caller may supply its own order instead. +/// +/// 返回适合贪心调度器的任务次序。 +/// +/// 该次序按加权价值递减排列，这是一个有效启发式：先放置贡献最大的任务， +/// 把价值最小的留给填补空隙。平局先按更早的截止时刻、再按标识符打破，故 +/// 对给定集合次序是确定的。 +/// +/// 它不保证找到最优计划。带资源约束的调度在一般情况下不可解，故启发式 +/// 是现实的选择，调用方亦可自行提供次序。 pub fn task_order(tasks: &[Task]) -> Vec { let mut ordered: Vec<&Task> = tasks.iter().collect(); ordered.sort_by(|first, second| {