harmos_runtime/operations/
lane.rs

1/* ***
2 *
3 * Harmos
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * ***
8 */
9
10/* === Modules === */
11
12/* === Re-Exports === */
13
14/* === Imports === */
15
16// Standard Library Imports
17use std::collections::BTreeMap;
18use std::sync::Arc;
19// Third Party Imports
20use tokio::sync::Semaphore;
21// Local Imports
22
23/* === Constants === */
24
25// The lane resident controls run in: unbounded, so a control that runs until
26// cancelled never holds a slot another call is waiting for.
27pub(crate) const RESIDENT: &str = "harmos.resident";
28
29/* === Macros === */
30
31/* === Type Aliases === */
32
33/* === Structs === */
34
35#[derive(Clone, Copy, Debug, PartialEq, Eq)]
36pub struct Capacity {
37    width: usize,
38}
39
40#[derive(Clone, Debug, Default)]
41pub struct LaneSet {
42    entries: Vec<(&'static str, Capacity)>,
43}
44
45#[derive(Clone)]
46pub(crate) struct Admission {
47    name: &'static str,
48    width: usize,
49    semaphore: Arc<Semaphore>,
50}
51
52pub(crate) struct Lanes {
53    lanes: BTreeMap<&'static str, Admission>,
54}
55
56/* === Enums === */
57
58/* === Traits === */
59
60pub trait Lane: Send + 'static {
61    fn name(&self) -> &'static str;
62    fn capacity(&self) -> Capacity;
63}
64
65/* === Implementations === */
66
67impl Capacity {
68    pub const fn serial() -> Self {
69        Self { width: 1 }
70    }
71
72    pub const fn concurrent(width: usize) -> Self {
73        Self { width }
74    }
75
76    pub const fn unbounded() -> Self {
77        Self { width: usize::MAX }
78    }
79
80    pub(crate) const fn width(self) -> usize {
81        self.width
82    }
83}
84
85impl LaneSet {
86    pub fn declared(entries: impl IntoIterator<Item = (&'static str, Capacity)>) -> Self {
87        Self { entries: entries.into_iter().collect() }
88    }
89
90    pub(crate) fn entries(self) -> Vec<(&'static str, Capacity)> {
91        self.entries
92    }
93
94    pub(crate) fn extend(&mut self, other: Self) {
95        self.entries.extend(other.entries);
96    }
97}
98
99impl Admission {
100    pub(crate) fn name(&self) -> &'static str {
101        self.name
102    }
103
104    pub(crate) fn bounded(&self) -> bool {
105        self.width != usize::MAX
106    }
107
108    pub(crate) fn semaphore(&self) -> Arc<Semaphore> {
109        Arc::clone(&self.semaphore)
110    }
111}
112
113impl Lanes {
114    pub(crate) fn freeze(declared: LaneSet) -> Result<Self, String> {
115        let mut lanes = BTreeMap::from([(
116            RESIDENT,
117            Admission { name: RESIDENT, width: usize::MAX, semaphore: Arc::new(Semaphore::new(Semaphore::MAX_PERMITS)) },
118        )]);
119
120        for (name, capacity) in declared.entries() {
121            if name.is_empty() {
122                return Err("a lane name must not be empty".to_owned());
123            }
124            if capacity.width() == 0 {
125                return Err(format!("lane `{name}` must admit at least one job"));
126            }
127            let admission = Admission {
128                name,
129                width: capacity.width(),
130                semaphore: Arc::new(Semaphore::new(capacity.width().min(Semaphore::MAX_PERMITS))),
131            };
132            if lanes.insert(name, admission).is_some() {
133                return Err(format!("lane `{name}` is declared more than once"));
134            }
135        }
136
137        Ok(Self { lanes })
138    }
139
140    pub(crate) fn get(&self, name: &str) -> Option<Admission> {
141        self.lanes.get(name).cloned()
142    }
143}
144
145/* === Public Functions === */
146
147/* === Private Functions === */
148
149/* === Tests === */
harmos_runtime/operations/lane.rs

harmos_runtime/operations/
lane.rs
