487 lines
18 KiB
Rust
487 lines
18 KiB
Rust
//! The schedule itself.
|
|
|
|
use crate::error::{ScheduleError, ScheduleErrorKind};
|
|
use crate::placement::{Evaluation, Placement, ResourceUsage};
|
|
use apsis_resource::ResourceId;
|
|
use apsis_task::TaskId;
|
|
use std::collections::BTreeMap;
|
|
|
|
/// A set of task placements.
|
|
///
|
|
/// The schedule stores placements in the order they were made and keeps an
|
|
/// index from task to placement, so that a lookup by task is direct. A task
|
|
/// may be placed at most once: placing it again is an error rather than a
|
|
/// silent overwrite, because a schedule that contains two placements for one
|
|
/// task is not a schedule.
|
|
///
|
|
/// 一组任务放置。
|
|
///
|
|
/// 该计划按放置发生的顺序保存各项，并维护从任务到放置的索引，故按任务查找
|
|
/// 是直接的。一个任务至多放置一次：重复放置是错误而非静默覆盖，因为含有
|
|
/// 同一任务两处放置的集合已不是一份计划。
|
|
#[derive(Debug, Clone, PartialEq, Default)]
|
|
pub struct Schedule {
|
|
placements: Vec<Placement>,
|
|
index: BTreeMap<usize, usize>,
|
|
}
|
|
|
|
impl Schedule {
|
|
/// Creates an empty schedule.
|
|
///
|
|
/// 创建一份空计划。
|
|
pub fn new() -> Self {
|
|
Self {
|
|
placements: Vec::new(),
|
|
index: BTreeMap::new(),
|
|
}
|
|
}
|
|
|
|
/// Returns the placements in the order they were made.
|
|
///
|
|
/// 返回按放置顺序排列的各项。
|
|
pub fn placements(&self) -> &[Placement] {
|
|
&self.placements
|
|
}
|
|
|
|
/// Returns the number of placements.
|
|
///
|
|
/// 返回放置的数量。
|
|
pub fn len(&self) -> usize {
|
|
self.placements.len()
|
|
}
|
|
|
|
/// Returns `true` when there are no placements.
|
|
///
|
|
/// 当没有放置时返回 `true`。
|
|
pub fn is_empty(&self) -> bool {
|
|
self.placements.is_empty()
|
|
}
|
|
|
|
/// Returns `true` when a task has been placed.
|
|
///
|
|
/// 当某任务已被放置时返回 `true`。
|
|
pub fn is_placed(&self, task: TaskId) -> bool {
|
|
self.index.contains_key(&task.index())
|
|
}
|
|
|
|
/// Returns the placement of a task.
|
|
///
|
|
/// 返回某任务的放置。
|
|
pub fn placement_of(&self, task: TaskId) -> Option<&Placement> {
|
|
self.index
|
|
.get(&task.index())
|
|
.map(|position| &self.placements[*position])
|
|
}
|
|
|
|
/// Places a task at a time.
|
|
///
|
|
/// The placement is checked against the task's window. The resources of
|
|
/// the task are recorded with the placement through the task itself, so
|
|
/// this method does not need them; the capacity check is performed by
|
|
/// [`Schedule::validate_capacity`], which needs the resources.
|
|
///
|
|
/// Returns an error when the task is already placed, when the start time
|
|
/// is not finite, or when the placement falls outside the task's window.
|
|
///
|
|
/// 把某任务放置在某时刻。
|
|
///
|
|
/// 放置会对照该任务的窗口校验。任务的资源通过任务本身随放置一同记录，
|
|
/// 故本方法无需它们；容量检查由需要资源的
|
|
/// [`Schedule::validate_capacity`] 完成。
|
|
///
|
|
/// 该任务已被放置、起始时刻非有限，或放置落在任务窗口之外时返回错误。
|
|
pub fn place(
|
|
&mut self,
|
|
task: &apsis_task::Task,
|
|
start: f64,
|
|
) -> Result<&Placement, ScheduleError> {
|
|
if !start.is_finite() {
|
|
return Err(ScheduleError::new(ScheduleErrorKind::InvalidStart)
|
|
.with_detail(format!("start {start}")));
|
|
}
|
|
if self.is_placed(task.id) {
|
|
return Err(ScheduleError::new(ScheduleErrorKind::AlreadyPlaced)
|
|
.with_detail(format!("{}", task.id)));
|
|
}
|
|
if start < task.earliest_start {
|
|
return Err(
|
|
ScheduleError::new(ScheduleErrorKind::BeforeWindow).with_detail(format!(
|
|
"task {} starts at {start}, before its window opens at {}",
|
|
task.id, task.earliest_start
|
|
)),
|
|
);
|
|
}
|
|
if start + task.duration > task.latest_end {
|
|
return Err(
|
|
ScheduleError::new(ScheduleErrorKind::AfterWindow).with_detail(format!(
|
|
"task {} ends at {}, after its window closes at {}",
|
|
task.id,
|
|
start + task.duration,
|
|
task.latest_end
|
|
)),
|
|
);
|
|
}
|
|
let placement = Placement::new(task.id, start, task.duration);
|
|
self.index.insert(task.id.index(), self.placements.len());
|
|
self.placements.push(placement);
|
|
Ok(self
|
|
.placements
|
|
.last()
|
|
.expect("the placement was just pushed"))
|
|
}
|
|
|
|
/// Removes the placement of a task.
|
|
///
|
|
/// Returns an error when the task is not placed.
|
|
///
|
|
/// 移除某任务的放置。
|
|
///
|
|
/// 该任务未被放置时返回错误。
|
|
pub fn unplace(&mut self, task: TaskId) -> Result<Placement, ScheduleError> {
|
|
let position = self.index.remove(&task.index()).ok_or_else(|| {
|
|
ScheduleError::new(ScheduleErrorKind::NotPlaced).with_detail(format!("{task}"))
|
|
})?;
|
|
let removed = self.placements.remove(position);
|
|
// Every placement after the removed one shifts down by one, so the
|
|
// index must be rebuilt. The schedule is small enough that this is
|
|
// cheaper than maintaining a linked structure.
|
|
// 被移除项之后的每项都前移一位，故索引须重建。计划规模足够小，
|
|
// 这比维护链式结构更划算。
|
|
self.rebuild_index();
|
|
Ok(removed)
|
|
}
|
|
|
|
/// Rebuilds the task to position index.
|
|
///
|
|
/// 重建从任务到位置的索引。
|
|
fn rebuild_index(&mut self) {
|
|
self.index.clear();
|
|
for (position, placement) in self.placements.iter().enumerate() {
|
|
self.index.insert(placement.task.index(), position);
|
|
}
|
|
}
|
|
|
|
/// Returns the placements that use a resource, in time order.
|
|
///
|
|
/// 返回使用某资源的放置，按时间排序。
|
|
pub fn placements_on(
|
|
&self,
|
|
resource: ResourceId,
|
|
tasks: &[apsis_task::Task],
|
|
) -> Vec<Placement> {
|
|
let mut selected: Vec<Placement> = self
|
|
.placements
|
|
.iter()
|
|
.filter(|placement| {
|
|
tasks
|
|
.iter()
|
|
.find(|task| task.id == placement.task)
|
|
.is_some_and(|task| task.requires(resource))
|
|
})
|
|
.copied()
|
|
.collect();
|
|
selected.sort_by(|first, second| {
|
|
first
|
|
.start
|
|
.partial_cmp(&second.start)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
});
|
|
selected
|
|
}
|
|
|
|
/// Returns `true` when two placements of different tasks overlap.
|
|
///
|
|
/// This checks the schedule against itself, ignoring the resources. Two
|
|
/// tasks on disjoint resources may legitimately overlap, so a caller that
|
|
/// wants to know whether a resource is overbooked should use
|
|
/// [`Schedule::validate_capacity`] instead.
|
|
///
|
|
/// 当两个不同任务的放置重叠时返回 `true`。
|
|
///
|
|
/// 这是计划与自身的比较，忽略资源。位于不相交资源上的两个任务本就可
|
|
/// 以合法重叠，故欲知某资源是否超订的调用方应改用
|
|
/// [`Schedule::validate_capacity`]。
|
|
pub fn has_overlapping_placements(&self) -> bool {
|
|
for (index, placement) in self.placements.iter().enumerate() {
|
|
if self.placements[..index]
|
|
.iter()
|
|
.any(|earlier| earlier.overlaps(placement))
|
|
{
|
|
return true;
|
|
}
|
|
}
|
|
false
|
|
}
|
|
|
|
/// Returns the total placed duration, in seconds.
|
|
///
|
|
/// 返回已放置的总时长，单位为秒。
|
|
pub fn scheduled_seconds(&self) -> f64 {
|
|
self.placements
|
|
.iter()
|
|
.map(|placement| placement.duration)
|
|
.sum()
|
|
}
|
|
|
|
/// Returns the earliest start of any placement.
|
|
///
|
|
/// Returns `None` when the schedule is empty.
|
|
///
|
|
/// 返回所有放置中最早的开始时刻。
|
|
///
|
|
/// 计划为空时返回 `None`。
|
|
pub fn earliest_start(&self) -> Option<f64> {
|
|
self.placements
|
|
.iter()
|
|
.map(|placement| placement.start)
|
|
.min_by(|first, second| {
|
|
first
|
|
.partial_cmp(second)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
})
|
|
}
|
|
|
|
/// Returns the latest end of any placement.
|
|
///
|
|
/// Returns `None` when the schedule is empty.
|
|
///
|
|
/// 返回所有放置中最晚的结束时刻。
|
|
///
|
|
/// 计划为空时返回 `None`。
|
|
pub fn latest_end(&self) -> Option<f64> {
|
|
self.placements
|
|
.iter()
|
|
.map(Placement::end)
|
|
.max_by(|first, second| {
|
|
first
|
|
.partial_cmp(second)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
})
|
|
}
|
|
|
|
/// Validates a schedule against a set of resources.
|
|
///
|
|
/// The check has two parts. First every placement must agree with the
|
|
/// requirements of its task, which catches a schedule built with a
|
|
/// different task list. Then, for each resource, the total demand placed
|
|
/// at any instant must not exceed the capacity.
|
|
///
|
|
/// The second check walks the placement boundaries of each resource in
|
|
/// time order, which is exact because the total demand is constant
|
|
/// between boundaries.
|
|
///
|
|
/// Returns an error describing the first violation.
|
|
///
|
|
/// 对照一组资源校验该计划。
|
|
///
|
|
/// 检查分两部分。其一，每处放置须与其任务的需求一致，这可捕获用另
|
|
/// 一份任务列表建成的计划。其二，对每个资源，任意瞬时的总需求不得超
|
|
/// 过容量。
|
|
///
|
|
/// 第二部分按时间序遍历各资源的放置边界，由于相邻边界之间总需求恒定，
|
|
/// 该遍历是精确的。
|
|
///
|
|
/// 返回描述首个违规的错误。
|
|
pub fn validate_capacity(
|
|
&self,
|
|
tasks: &[apsis_task::Task],
|
|
resources: &apsis_resource::ResourceSet,
|
|
) -> Result<(), ScheduleError> {
|
|
for placement in &self.placements {
|
|
let task = tasks
|
|
.iter()
|
|
.find(|task| task.id == placement.task)
|
|
.ok_or_else(|| {
|
|
ScheduleError::new(ScheduleErrorKind::RequirementMismatch)
|
|
.with_detail(format!("{} is not in the task list", placement.task))
|
|
})?;
|
|
if (placement.duration - task.duration).abs() > 1e-12 {
|
|
return Err(ScheduleError::new(ScheduleErrorKind::RequirementMismatch)
|
|
.with_detail(format!(
|
|
"{} is placed for {} s but takes {} s",
|
|
task.id, placement.duration, task.duration
|
|
)));
|
|
}
|
|
}
|
|
|
|
for resource in resources.resources() {
|
|
// The boundaries at which the total demand can change.
|
|
// 总需求可能发生变化的各边界。
|
|
let mut events: Vec<(f64, f64)> = Vec::new();
|
|
for placement in &self.placements {
|
|
let Some(task) = tasks.iter().find(|task| task.id == placement.task) else {
|
|
continue;
|
|
};
|
|
if let Some(demand) = task.demand_for(resource.id) {
|
|
events.push((placement.start, demand));
|
|
events.push((placement.end(), -demand));
|
|
}
|
|
}
|
|
if events.is_empty() {
|
|
continue;
|
|
}
|
|
// Sort by time, with a release before an acquisition at the same
|
|
// instant so that two placements that touch are not counted as
|
|
// overlapping.
|
|
// 按时间排序；同一瞬先释放后获取，使两个相接的放置不被计为
|
|
// 重叠。
|
|
events.sort_by(|first, second| {
|
|
first
|
|
.0
|
|
.partial_cmp(&second.0)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
.then_with(|| {
|
|
first
|
|
.1
|
|
.partial_cmp(&second.1)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
})
|
|
});
|
|
|
|
let mut current = 0.0;
|
|
for (time, change) in events {
|
|
current += change;
|
|
if current > resource.capacity() + 1e-9 {
|
|
return Err(ScheduleError::new(ScheduleErrorKind::CapacityExceeded)
|
|
.with_detail(format!(
|
|
"{} carries demand {} against capacity {} at {time}",
|
|
resource.id,
|
|
current,
|
|
resource.capacity()
|
|
)));
|
|
}
|
|
}
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
/// Evaluates the schedule against a task list and a resource set.
|
|
///
|
|
/// The evaluation reports the counts, the makespan, and the usage of each
|
|
/// resource. The peak demand of a resource is found by the same event
|
|
/// sweep that the capacity check uses, so the two agree.
|
|
///
|
|
/// 对照任务列表与资源集合评估该计划。
|
|
///
|
|
/// 评估给出各项计数、makespan 以及每个资源的使用情况。资源的峰值
|
|
/// 需求由与容量检查相同的事件扫掠求得，故二者一致。
|
|
pub fn evaluate(
|
|
&self,
|
|
tasks: &[apsis_task::Task],
|
|
resources: &apsis_resource::ResourceSet,
|
|
) -> Evaluation {
|
|
let mut resource_usage = Vec::with_capacity(resources.len());
|
|
for resource in resources.resources() {
|
|
let mut events: Vec<(f64, f64)> = Vec::new();
|
|
let mut placement_count = 0;
|
|
for placement in &self.placements {
|
|
let Some(task) = tasks.iter().find(|task| task.id == placement.task) else {
|
|
continue;
|
|
};
|
|
if let Some(demand) = task.demand_for(resource.id) {
|
|
events.push((placement.start, demand));
|
|
events.push((placement.end(), -demand));
|
|
placement_count += 1;
|
|
}
|
|
}
|
|
events.sort_by(|first, second| {
|
|
first
|
|
.0
|
|
.partial_cmp(&second.0)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
.then_with(|| {
|
|
first
|
|
.1
|
|
.partial_cmp(&second.1)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
})
|
|
});
|
|
|
|
let mut current = 0.0;
|
|
let mut peak = 0.0_f64;
|
|
let mut busy = 0.0_f64;
|
|
let mut previous: Option<f64> = None;
|
|
for (time, change) in events {
|
|
if let Some(previous) = previous {
|
|
if current > 0.0 {
|
|
busy += time - previous;
|
|
}
|
|
}
|
|
current += change;
|
|
peak = peak.max(current);
|
|
previous = Some(time);
|
|
}
|
|
|
|
resource_usage.push(ResourceUsage {
|
|
resource: resource.id,
|
|
peak_demand: peak,
|
|
busy_seconds: busy,
|
|
placement_count,
|
|
});
|
|
}
|
|
|
|
Evaluation {
|
|
placed_count: self.placements.len(),
|
|
offered_count: tasks.len(),
|
|
scheduled_seconds: self.scheduled_seconds(),
|
|
makespan_start: self.earliest_start().unwrap_or(0.0),
|
|
makespan_end: self.latest_end().unwrap_or(0.0),
|
|
resource_usage,
|
|
}
|
|
}
|
|
|
|
/// Returns the schedule sorted by start time, leaving the original alone.
|
|
///
|
|
/// A schedule is stored in the order it was built, which is the order a
|
|
/// scheduler considered the tasks. A caller that wants to read the plan
|
|
/// in time order uses this.
|
|
///
|
|
/// 返回按开始时刻排序的计划副本，原计划不变。
|
|
///
|
|
/// 计划按其构建顺序存储，即调度器考虑任务的顺序。欲按时间阅读该计
|
|
/// 划的调用方使用本方法。
|
|
pub fn in_time_order(&self) -> Vec<Placement> {
|
|
let mut ordered = self.placements.clone();
|
|
ordered.sort_by(|first, second| {
|
|
first
|
|
.start
|
|
.partial_cmp(&second.start)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
.then_with(|| first.task.cmp(&second.task))
|
|
});
|
|
ordered
|
|
}
|
|
|
|
/// Returns the time at which a resource becomes free if it is busy at a
|
|
/// given instant.
|
|
///
|
|
/// Returns `None` when the resource is idle there. This is what a
|
|
/// sequential scheduler asks when it looks for the next gap.
|
|
///
|
|
/// 若某资源在给定瞬时忙碌，返回其变为空闲的时刻。
|
|
///
|
|
/// 该资源在彼处空闲时返回 `None`。顺序调度器寻找下一个空隙时正是
|
|
/// 询问这一点。
|
|
pub fn resource_busy_until(
|
|
&self,
|
|
resource: ResourceId,
|
|
tasks: &[apsis_task::Task],
|
|
time: f64,
|
|
) -> Option<f64> {
|
|
self.placements
|
|
.iter()
|
|
.filter(|placement| {
|
|
tasks
|
|
.iter()
|
|
.find(|task| task.id == placement.task)
|
|
.is_some_and(|task| task.requires(resource) && placement.covers(time))
|
|
})
|
|
.map(Placement::end)
|
|
.max_by(|first, second| {
|
|
first
|
|
.partial_cmp(second)
|
|
.unwrap_or(core::cmp::Ordering::Equal)
|
|
})
|
|
}
|
|
}
|