shed_machines 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 061e0fb85399ec23ed73e673a6ca55d406b3c1a775a6c3fade1a84e836bcb615
-  data.tar.gz: e02e410d9a5909bf71101a5d5cbe80cfc70e1aa6a42e0a6c3eb6509115078cb5
+  metadata.gz: c1963be072e29aa88de44cf7a973c02baa5e4a56f7df026c35d289cce6d396f2
+  data.tar.gz: 79b9212417e38b688989b41e65dd49853d3a1c96ddad46b543d2d305dcba3cb3
 SHA512:
-  metadata.gz: 274e603824e19a217e2762cec86d6c43b1756ac955b753afb1061b9b5ed4dcd96a745b92c10c96fe6b80d5221fb95be4d3b109ce652d857d76d2557d096c0b78
-  data.tar.gz: 6e928923121a47f7c38f963c3f5c09b4e77c408c7b7a6d122f18b1587e54983949c2067cd2d73b3e4d16784bc51b03ae2a5a7bd29967f4685ec6dc40366781ab
+  metadata.gz: 66a0334e48d91bae8ff3c0b1ced6b2482ca6a19bd42662de5659d869bf401d4077b1dacfe892d80e114263a2d2843e058132aae9032e3b828981a4f09418809b
+  data.tar.gz: b3f93302bac8c313c4ce1b2c02257f0e9172949361dca756c32f6e6fa21554f8deec40a626dd2fd314a3ac4d2cd8a9ac9d28faf590dca6c04a848ea544608fb0

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.1.2](https://github.com/seuros/shed_machines/compare/shed_machines/v0.1.1...shed_machines/v0.1.2) (2026-11-01)
+
+
+### Bug Fixes
+
+* a republished platform gem is skipped, not fatal ([35352a1](https://github.com/seuros/shed_machines/commit/35352a16dd73e19cf7e7661ce362f96e016a2cac))
+* window the Vegas baseline so it cannot pin to one lucky call ([9cea8fa](https://github.com/seuros/shed_machines/commit/9cea8fa82f1fd9ab99f0bcf7a67a36ee24cd61ec))
+
 ## [0.1.1](https://github.com/seuros/shed_machines/compare/shed_machines-v0.1.0...shed_machines/v0.1.1) (2026-11-01)
 
 

data/Cargo.lock

@@ -240,11 +240,11 @@ checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
 
 [[package]]
 name = "shed-machines"
-version = "0.2.0"
+version = "0.2.1"
 
 [[package]]
 name = "shed_machines_native"
-version = "0.1.1"
+version = "0.1.2"
 dependencies = [
  "magnus",
  "shed-machines",

data/README.md

@@ -70,15 +70,32 @@ control.limit                                                   # => 8
 ```
 
 `Vegas` infers queue depth from the gap between the current round-trip time and
-the best one it has seen, because latency alone cannot tell a slow dependency
-from a deep queue. It grows while fewer than `alpha` calls look queued, shrinks
-above `beta`, and holds in between.
+the smallest one it has seen recently, because latency alone cannot tell a slow
+dependency from a deep queue. It grows while fewer than `alpha` calls look
+queued, shrinks above `beta`, and holds in between.
 
 ```ruby
 control = ShedMachines::Vegas.new(limit: 10, min: 1, max: 200, alpha: 3, beta: 6)
 control.best_rtt     # => nil, until the first completed call
 ```
 
+That inference only holds when any two calls would take about as long on an idle
+dependency. Over a mix whose service times differ by orders of magnitude the
+baseline settles on the fastest kind of work, every slower call reads as a deep
+queue, and the limit sinks to `min` and stays there — tuning `alpha` and `beta`
+cannot fix it, because the signal is measuring the wrong thing. Use `Aimd` for
+heterogeneous work, since it steers on outcomes rather than latency, or give
+each class of work its own `Vegas`.
+
+The baseline is the smallest round-trip time in the current window of
+`DEFAULT_BASELINE_WINDOW` samples or the one before it, so one unusually fast
+call cannot pin it for the life of the process and a dependency that
+legitimately slows down is believed within two windows.
+
+```ruby
+control = ShedMachines::Vegas.new(limit: 10).baseline_window(250)
+```
+
 Both take `outcome: :ok` or `outcome: :overload`, where overload means the call
 timed out, was rejected, or otherwise says the dependency is loaded. Anything
 else raises `ArgumentError`. Both clamp a starting limit into `min..max`, which
@@ -152,6 +169,7 @@ The Ruby constants mirror the crate's, with the same names and values.
 | `Vegas::DEFAULT_ALPHA`             | 3           |
 | `Vegas::DEFAULT_BETA`              | 6           |
 | `Vegas::OVERLOAD_DIVISOR`          | 2           |
+| `Vegas::DEFAULT_BASELINE_WINDOW`   | 1000        |
 | `Codel::DEFAULT_TARGET_NS`         | 5_000_000   |
 | `Codel::DEFAULT_INTERVAL_NS`       | 100_000_000 |
 | `Budget::DEFAULT_MULTIPLIER`       | 2.0         |

data/ext/shed_machines_native/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "shed-machines"
-version = "0.2.0"
+version = "0.2.1"
 edition.workspace = true
 rust-version.workspace = true
 authors = ["Abdelkader Boudih <oss@seuros.com>"]

data/ext/shed_machines_native/core/src/vegas.rs

@@ -14,12 +14,41 @@ pub const DEFAULT_BETA: u32 = 6;
 /// Denominator of the fraction kept after an overload.
 pub const OVERLOAD_DIVISOR: u32 = 2;
 
+/// Samples one baseline window spans. The baseline is the smallest round-trip
+/// time in the current window or the one before it, so it always reflects
+/// between this many recent calls and twice as many.
+pub const DEFAULT_BASELINE_WINDOW: u32 = 1_000;
+
 /// Calls added or removed per sample.
 const STEP: u32 = 1;
 
 /// Estimates how many calls are queued rather than working, from the gap
-/// between the current round-trip time and the best one ever seen, then steers
-/// the limit to keep that estimate inside a band.
+/// between the current round-trip time and the smallest one seen recently, then
+/// steers the limit to keep that estimate inside a band.
+///
+/// # The work has to be homogeneous
+///
+/// The queue estimate reads every nanosecond above the baseline as time spent
+/// waiting, which only holds when any two calls would take about as long on an
+/// idle dependency. Over a mix whose service times differ by orders of
+/// magnitude the baseline settles on the fastest kind of work, every slower
+/// call looks like a deep queue, and the limit sinks to [`Bounds`]' floor and
+/// stays there — no amount of tuning `alpha` and `beta` fixes it, because the
+/// signal itself is measuring the wrong thing. Give heterogeneous work
+/// [`Aimd`](crate::Aimd) instead: it steers on outcomes rather than latency, so
+/// a slow call is not mistaken for a queued one. One `Vegas` per class of work
+/// is the other way out.
+///
+/// # The baseline is windowed
+///
+/// A baseline that only ever shrank would pin itself to the luckiest call the
+/// process ever made and never recover, so one unusually fast sample, or a
+/// dependency that has since legitimately slowed down, would hold the limit at
+/// the floor for good. The baseline is instead the smallest round-trip time in
+/// the current window of [`DEFAULT_BASELINE_WINDOW`] samples or in the one
+/// before it, which keeps it stable while traffic is steady and lets it rise
+/// within two windows when the dependency changes. Set the span with
+/// [`baseline_window`](Self::baseline_window).
 ///
 /// ```
 /// use shed_machines::{Bounds, Controller, Sample, Vegas};
@@ -38,7 +67,13 @@ const STEP: u32 = 1;
 pub struct Vegas {
     bounds: Bounds,
     limit: u32,
-    best_rtt_ns: u64,
+    /// Smallest round-trip time in the window being filled, and in the one
+    /// before it. [`u64::MAX`] stands for a window with nothing in it.
+    current_ns: u64,
+    previous_ns: u64,
+    /// Samples into the current window, and how many it holds.
+    seen: u32,
+    window: u32,
     alpha: u32,
     beta: u32,
 }
@@ -49,7 +84,10 @@ impl Vegas {
         Self {
             bounds,
             limit: bounds.clamp(limit),
-            best_rtt_ns: u64::MAX,
+            current_ns: u64::MAX,
+            previous_ns: u64::MAX,
+            seen: 0,
+            window: DEFAULT_BASELINE_WINDOW,
             alpha: DEFAULT_ALPHA,
             beta: DEFAULT_BETA,
         }
@@ -63,23 +101,57 @@ impl Vegas {
         self
     }
 
-    /// The best round-trip time seen so far, the stand-in for zero queueing.
+    /// Samples one baseline window spans, at least one. A shorter window
+    /// follows a dependency whose idle latency drifts; a longer one holds a
+    /// steadier baseline when traffic is bursty.
+    #[must_use]
+    pub const fn baseline_window(mut self, samples: u32) -> Self {
+        self.window = samples;
+        self
+    }
+
+    /// The smallest round-trip time in the last window or two, the stand-in for
+    /// zero queueing.
     #[must_use]
     pub const fn best_rtt_ns(&self) -> Option<u64> {
-        if self.best_rtt_ns == u64::MAX {
+        let baseline = self.baseline();
+        if baseline == u64::MAX {
             None
         } else {
-            Some(self.best_rtt_ns)
+            Some(baseline)
+        }
+    }
+
+    const fn baseline(&self) -> u64 {
+        if self.current_ns < self.previous_ns {
+            self.current_ns
+        } else {
+            self.previous_ns
+        }
+    }
+
+    /// Takes `rtt_ns` into the window being filled, retiring that window once
+    /// it is full so the baseline cannot outlive the traffic it came from.
+    const fn rebase(&mut self, rtt_ns: u64) {
+        if rtt_ns < self.current_ns {
+            self.current_ns = rtt_ns;
+        }
+        self.seen += 1;
+        if self.seen >= self.window {
+            self.previous_ns = self.current_ns;
+            self.current_ns = u64::MAX;
+            self.seen = 0;
         }
     }
 
     /// `limit * (rtt - best) / rtt`, the Vegas estimate of how many calls in
     /// flight are waiting rather than working.
     fn queued(&self, rtt_ns: u64) -> u64 {
-        if rtt_ns == 0 || self.best_rtt_ns >= rtt_ns {
+        let baseline = self.baseline();
+        if rtt_ns == 0 || baseline >= rtt_ns {
             return 0;
         }
-        let excess = rtt_ns - self.best_rtt_ns;
+        let excess = rtt_ns - baseline;
         let scaled = u128::from(self.limit) * u128::from(excess) / u128::from(rtt_ns);
         u64::try_from(scaled).unwrap_or(u64::MAX)
     }
@@ -92,7 +164,7 @@ impl Controller for Vegas {
             return;
         }
 
-        self.best_rtt_ns = self.best_rtt_ns.min(sample.rtt_ns);
+        self.rebase(sample.rtt_ns);
         let queued = self.queued(sample.rtt_ns);
 
         self.limit = if queued < u64::from(self.alpha) {

data/ext/shed_machines_native/ffi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "shed_machines_native"
-version = "0.1.1"
+version = "0.1.2"
 edition.workspace = true
 rust-version.workspace = true
 authors = ["Abdelkader Boudih <oss@seuros.com>"]

data/ext/shed_machines_native/ffi/src/vegas.rs

@@ -5,10 +5,12 @@ use std::cell::RefCell;
 use magnus::scan_args::scan_args;
 use magnus::typed_data::Obj;
 use magnus::{Error, RHash, RModule, Ruby, Value, function, method, prelude::*};
-use shed_machines::vegas::{DEFAULT_ALPHA, DEFAULT_BETA, OVERLOAD_DIVISOR};
+use shed_machines::vegas::{
+    DEFAULT_ALPHA, DEFAULT_BASELINE_WINDOW, DEFAULT_BETA, OVERLOAD_DIVISOR,
+};
 use shed_machines::{Controller, Vegas};
 
-use crate::{observe, opening, to_seconds};
+use crate::{Whole, observe, opening, to_seconds};
 
 #[magnus::wrap(class = "ShedMachines::Vegas", free_immediately, size)]
 struct Wrapper(RefCell<Vegas>);
@@ -31,7 +33,14 @@ impl Wrapper {
         self.0.borrow().limit()
     }
 
-    /// The best round-trip time seen so far, in seconds.
+    /// Samples one baseline window spans. Chainable, like the Rust builder.
+    fn baseline_window(rb_self: Obj<Self>, Whole(samples): Whole<u32>) -> Obj<Self> {
+        let windowed = rb_self.0.borrow().baseline_window(samples);
+        *rb_self.0.borrow_mut() = windowed;
+        rb_self
+    }
+
+    /// The smallest round-trip time in the last window or two, in seconds.
     fn best_rtt(&self) -> Option<f64> {
         self.0.borrow().best_rtt_ns().map(to_seconds)
     }
@@ -52,9 +61,11 @@ pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
     class.const_set("DEFAULT_ALPHA", DEFAULT_ALPHA)?;
     class.const_set("DEFAULT_BETA", DEFAULT_BETA)?;
     class.const_set("OVERLOAD_DIVISOR", OVERLOAD_DIVISOR)?;
+    class.const_set("DEFAULT_BASELINE_WINDOW", DEFAULT_BASELINE_WINDOW)?;
     class.define_singleton_method("new", function!(Wrapper::new, -1))?;
     class.define_method("observe", method!(Wrapper::observe, -1))?;
     class.define_method("limit", method!(Wrapper::limit, 0))?;
+    class.define_method("baseline_window", method!(Wrapper::baseline_window, 1))?;
     class.define_method("best_rtt", method!(Wrapper::best_rtt, 0))?;
     class.define_method("inspect", method!(Wrapper::inspect, 0))?;
     Ok(())

data/lib/shed_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShedMachines
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shed_machines
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Abdelkader Boudih