1use std::time::{Duration, Instant};
4
5#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
7pub enum BudgetMode {
8 #[default]
10 LatencyPriority,
11 BudgetPriority,
13 FailClosed,
15}
16
17#[derive(Clone, Copy, Debug)]
19pub struct BudgetConfig {
20 pub enabled: bool,
22 pub mode: BudgetMode,
24 pub budget_per_sec_cap: Option<f64>,
26 pub budget_per_sec_floor: Option<f64>,
28 pub budget_fraction: f64,
30 pub default_capacity_per_sec: f64,
32 pub early_flush_fill_ratio: f64,
34 pub early_flush_cooldown: Duration,
36 pub early_flush_max_queued_bytes: usize,
40 pub early_flush_idle: Duration,
44 pub admission_timeout: Duration,
46}
47
48impl Default for BudgetConfig {
49 fn default() -> Self {
50 Self {
51 enabled: true,
52 mode: BudgetMode::LatencyPriority,
53 budget_per_sec_cap: None,
54 budget_per_sec_floor: None,
55 budget_fraction: 0.5,
56 default_capacity_per_sec: 50.0,
58 early_flush_fill_ratio: 0.5,
59 early_flush_cooldown: Duration::from_millis(5),
60 early_flush_max_queued_bytes: 4 * 1024 * 1024,
62 early_flush_idle: Duration::from_millis(10),
64 admission_timeout: Duration::from_millis(100),
65 }
66 }
67}
68
69impl BudgetConfig {
70 pub fn validate(&self) -> Result<(), String> {
72 if let (Some(cap), Some(floor)) = (self.budget_per_sec_cap, self.budget_per_sec_floor)
73 && floor > cap
74 {
75 return Err(format!(
76 "budget_per_sec_floor ({floor}) > budget_per_sec_cap ({cap})"
77 ));
78 }
79 if !(0.0..=1.0).contains(&self.budget_fraction) {
80 return Err("budget_fraction must be in [0, 1]".into());
81 }
82 if self.default_capacity_per_sec < 0.0 {
83 return Err("default_capacity_per_sec must be >= 0".into());
84 }
85 Ok(())
86 }
87
88 pub fn effective_budget_per_sec(
90 &self,
91 startup_capacity: Option<f64>,
92 ongoing_capacity: Option<f64>,
93 ) -> f64 {
94 let capacity = ongoing_capacity
95 .or(startup_capacity)
96 .unwrap_or(self.default_capacity_per_sec)
97 .max(0.0);
98 let mut effective = capacity * self.budget_fraction;
99 if let Some(cap) = self.budget_per_sec_cap {
100 effective = effective.min(cap);
101 }
102 if let Some(floor) = self.budget_per_sec_floor {
103 effective = effective.max(floor);
104 if let Some(cap) = self.budget_per_sec_cap {
105 effective = effective.min(cap);
106 }
107 }
108 effective
109 }
110}
111
112#[derive(Debug)]
114pub struct BudgetRuntime {
115 pub config: BudgetConfig,
116 pub tokens: f64,
117 pub effective_budget_per_sec: f64,
118 pub last_refill: Instant,
119 pub predicted_media_ops: f64,
120 pub last_early_flush: Option<Instant>,
121 pub media_ops_total: u64,
122 pub overdraft_total: u64,
123 pub flushes_total: u64,
124 pub undersized_deadline_flushes: u64,
125 pub startup_capacity: Option<f64>,
126 pub ongoing_capacity: Option<f64>,
127 media_ops_ewma: f64,
129 ewma_inited: bool,
130}
131
132impl BudgetRuntime {
133 pub fn new(config: BudgetConfig) -> Self {
134 let effective = config.effective_budget_per_sec(None, None);
135 Self {
136 config,
137 tokens: effective.max(1.0),
138 effective_budget_per_sec: effective,
139 last_refill: Instant::now(),
140 predicted_media_ops: 1.0,
141 last_early_flush: None,
142 media_ops_total: 0,
143 overdraft_total: 0,
144 flushes_total: 0,
145 undersized_deadline_flushes: 0,
146 startup_capacity: None,
147 ongoing_capacity: None,
148 media_ops_ewma: 1.0,
149 ewma_inited: false,
150 }
151 }
152
153 pub fn refill(&mut self, now: Instant) {
154 let dt = now.duration_since(self.last_refill).as_secs_f64();
155 if dt <= 0.0 {
156 return;
157 }
158 let burst = self.effective_budget_per_sec.max(1.0);
159 self.tokens = (self.tokens + dt * self.effective_budget_per_sec).min(burst);
160 self.last_refill = now;
161 }
162
163 pub fn fill_ratio(&self) -> f64 {
164 let burst = self.effective_budget_per_sec.max(1.0);
165 (self.tokens / burst).clamp(0.0, 1.0)
166 }
167
168 pub fn allow_early_flush(
175 &self,
176 now: Instant,
177 queued_bytes: usize,
178 last_enqueue: Option<Instant>,
179 ) -> bool {
180 if !self.config.enabled {
181 return false;
182 }
183 let max_q = self.config.early_flush_max_queued_bytes;
184 if max_q > 0 && queued_bytes > max_q {
185 return false;
186 }
187 let idle_need = self.config.early_flush_idle;
188 if !idle_need.is_zero() {
189 let Some(last) = last_enqueue else {
190 return false;
191 };
192 if now.duration_since(last) < idle_need {
193 return false;
194 }
195 }
196 if self.fill_ratio() < self.config.early_flush_fill_ratio {
197 return false;
198 }
199 if let Some(last) = self.last_early_flush
200 && now.duration_since(last) < self.config.early_flush_cooldown
201 {
202 return false;
203 }
204 true
205 }
206
207 pub fn note_early_flush(&mut self, now: Instant) {
208 self.last_early_flush = Some(now);
209 }
210
211 pub fn consume_after_flush(&mut self, media_ops: u64, now: Instant) {
213 self.refill(now);
214 let cost = media_ops as f64;
215 if cost <= self.tokens {
216 self.tokens -= cost;
217 } else {
218 self.overdraft_total += (cost - self.tokens).ceil() as u64;
219 self.tokens = 0.0;
220 }
221 self.media_ops_total += media_ops;
222 self.flushes_total += 1;
223 const ALPHA: f64 = 0.2;
225 if !self.ewma_inited {
226 self.media_ops_ewma = cost.max(0.1);
227 self.ewma_inited = true;
228 } else {
229 self.media_ops_ewma = ALPHA * cost + (1.0 - ALPHA) * self.media_ops_ewma;
230 }
231 self.predicted_media_ops = self.media_ops_ewma.max(0.1);
232 }
236
237 pub fn can_admit_now(&mut self, now: Instant) -> bool {
240 if !self.config.enabled {
241 return true;
242 }
243 self.refill(now);
244 match self.config.mode {
245 BudgetMode::LatencyPriority => true,
246 BudgetMode::BudgetPriority | BudgetMode::FailClosed => {
247 self.tokens >= self.predicted_media_ops * 0.5
248 }
249 }
250 }
251
252 pub fn reserve_for_fail_closed(&mut self, now: Instant) -> bool {
253 if !self.config.enabled || self.config.mode != BudgetMode::FailClosed {
254 return true;
255 }
256 self.refill(now);
257 let need = self.predicted_media_ops;
258 if self.tokens >= need {
259 self.tokens -= need;
260 true
261 } else {
262 false
263 }
264 }
265}
266
267#[derive(Clone, Copy, Debug, PartialEq, Eq)]
269pub enum EffectiveReason {
270 Configured,
272 ConfigCap,
274 StartupProbe,
276 Ongoing,
278 DefaultCapacity,
280 Disabled,
282}
283
284#[derive(Clone, Debug, PartialEq)]
286pub struct EffectiveKnob<T: Clone> {
287 pub configured: Option<T>,
289 pub startup_measured: Option<T>,
291 pub ongoing_measured: Option<T>,
293 pub effective: T,
295 pub reason: EffectiveReason,
297}
298
299#[derive(Clone, Debug)]
301pub struct PipelineSnapshot {
302 pub budget_per_sec: EffectiveKnob<f64>,
304 pub effective_linger_ms: EffectiveKnob<u64>,
306 pub max_linger_ms: u64,
308 pub token_fill_ratio: f64,
310 pub media_ops_total: u64,
312 pub overdraft_total: u64,
314 pub flushes_total: u64,
316 pub undersized_deadline_flushes: u64,
318 pub predicted_media_ops: f64,
320 pub budget_enabled: bool,
322 pub budget_mode: BudgetMode,
324}