priority_machines 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 336b8504ae6121373ba3e2b2b4e9b3750c3479796a6c06cd3da16c74daee171b
+  data.tar.gz: 0c5d3ec5bf92de2252dff7494e4adffd3395f507bab800845211e27377792104
+SHA512:
+  metadata.gz: 1eac9da160ac88331dc341f9731b706be2a4e991407d32dea9f7ab6943fdcac70b366feeed1cfc199fb7687f670e1a289ef5131a9001a183cbb27a8a0d63052d
+  data.tar.gz: d1ecc552bf3b4b08f985e2e24ab66e9b622d5092420857067cadc93cd8fe107c90e3d34cdb6ecbb77beb12908beaae8e625658df9ddcfc06591206d738a4c3ae

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.1.5](https://github.com/seuros/priority_machines/compare/priority_machines/v0.1.4...priority_machines/v0.1.5) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([1d389af](https://github.com/seuros/priority_machines/commit/1d389af51eacb70fe595028c381c68cb9d556f51))
+
+## [0.1.4](https://github.com/seuros/priority_machines/compare/priority_machines/v0.1.3...priority_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([37e58c0](https://github.com/seuros/priority_machines/commit/37e58c0575a088807db99d38ea820d87dde956b8))
+
+## [0.1.3](https://github.com/seuros/priority_machines/compare/priority_machines/v0.1.2...priority_machines/v0.1.3) (2026-11-06)
+
+
+### Features
+
+* plain round robin scheduler in the core ([315e567](https://github.com/seuros/priority_machines/commit/315e5677ab93d677c71847233abcaa2bad5a7f4e))
+
+## [0.1.2](https://github.com/seuros/priority_machines/compare/priority_machines/v0.1.1...priority_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* cross builds no longer compile for the host ([dcf3aac](https://github.com/seuros/priority_machines/commit/dcf3aaccd145677feb6f61ea2fbd3d7e7f3e120a))
+
+## [0.1.1](https://github.com/seuros/priority_machines/compare/priority_machines-v0.1.0...priority_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([ea040c3](https://github.com/seuros/priority_machines/commit/ea040c3e486d5b77a9eb4c68a8ac493399df8323))

data/Cargo.toml

@@ -0,0 +1,26 @@
+[workspace]
+members = ["ext/priority_machines_native/core", "ext/priority_machines_native/ffi"]
+default-members = ["ext/priority_machines_native/core"]
+resolver = "3"
+
+[workspace.dependencies]
+priority-machines = { path = "ext/priority_machines_native/core" }
+magnus = { version = "0.9.3", default-features = false }
+rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api-compiled-fallback"] }
+
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+license = "MIT"
+
+[workspace.lints.rust]
+unsafe_code = "deny"
+unused_must_use = "warn"
+missing_docs = "warn"
+
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+unwrap_used = "deny"
+expect_used = "deny"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,184 @@
+# PriorityMachines
+
+> Everyone's job is urgent. Someone still has to pick who goes next. 🚀
+
+Three ways to answer "which lane now?" for Ruby. Weighted round robin hands out turns by weight. Deficit round robin hands out turns by cost, so a lane full of heavy jobs can't hog the worker. Earliest deadline first picks whoever is closest to being late. You keep the queues. The scheduler just points.
+
+## Quick Start
+
+```bash
+gem 'priority_machines'
+```
+
+```ruby
+# Three tenants, three queues. Enterprise gets three turns for every one the others get.
+turns = PriorityMachines::WeightedRoundRobin.new(weights: [3, 1, 1])
+
+loop do
+  ready = queues.map { |q| !q.empty? }        # [true, false, true]
+  lane = turns.select(ready) or break          # => 0, 0, 0, 2, 0, 0, 0, 2 ...
+  run(queues[lane].shift)
+end
+```
+
+Weighted by cost instead of count? Tell it what the next job in each lane will cost:
+
+```ruby
+credit = PriorityMachines::DeficitRoundRobin.new(quanta: [4, 2])
+credit.select([3, 1])   # => 0, lane 0 has 4 credits and its head costs 3
+```
+
+Racing a clock? Give it the deadlines and it points at the nearest one:
+
+```ruby
+PriorityMachines.earliest_deadline([nil, 2.5, 1.0])   # => 2
+```
+
+## A Message to the Resistance
+
+So you have one worker pool and three customers. The big one uploads a 40 GB CSV every night. The small ones upload a contact form. Your queue is FIFO, which is a polite way of saying the contact forms wait behind 40 GB of someone else's rows.
+
+You tried priority levels. Now the big customer's jobs are all "high" too, because their account manager asked nicely.
+
+The problem was never the ordering. It's that "next" has no memory. Round robin fixes count: everyone gets a turn. But a turn that costs a million rows is not the same as a turn that costs one, so you need a scheduler that remembers who already spent their share. And when the question is "who is about to miss an SLA," neither of those is the answer; the deadline is.
+
+This gem is those three answers, with nothing else attached. No threads, no queues, no clock. You ask, it points at a lane.
+
+## Chapter 1: Stardate 2025.186, the AMS Liu
+
+> **AMS Liu**, NCC-4215, *Liu*-class dispatch escort.
+> Every shuttle says its launch is urgent. Someone still has to order the queue.
+
+The escort doesn't fly anyone anywhere. It stands on the pad with a clipboard. Three bays, three pilots all claiming priority. The escort knows how many launches each bay was promised, how much fuel each launch burns, and which flight plan runs out of window first. It points. The bay launches. It points again.
+
+On the pad, a dispatcher mutters:
+
+```ruby
+def next_job
+  jobs.sort_by { |j| [-j.priority, j.enqueued_at] }.first
+end
+```
+
+"That," says the escort, "is why the hangar is full of contact forms."
+
+## The Flight Plan
+
+Each scheduler keeps a little state per lane and moves it on every `select`.
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+    idle --> pointing: select(lanes)
+    pointing --> idle: lane chosen, its share spent
+    pointing --> idle: nothing ready, nil
+    idle --> idle: deactivate(lane), unspent share discarded
+```
+
+The night the big customer's import finally waited its turn:
+
+```mermaid
+sequenceDiagram
+    participant W as Worker
+    participant S as DeficitRoundRobin quanta [4, 2]
+    participant B as Bulk import lane
+    participant F as Contact form lane
+
+    W->>S: select([10, 1])
+    Note over S: bulk has 4 credits, needs 10. Form has 2, needs 1.
+    S-->>W: 1
+    W->>F: run one form
+    W->>S: select([10, 1])
+    S-->>W: 1
+    W->>F: run one form
+    W->>S: select([10, 1])
+    S-->>W: 1
+    W->>S: select([10, 1])
+    S-->>W: 1
+    W->>S: select([10, 1])
+    Note over S: bulk has saved up 12 credits now.
+    S-->>W: 0
+    W->>B: run the import
+```
+
+## Weighted Round Robin
+
+One turn per weight unit, round after round. Pass an array of booleans saying which lanes have something waiting.
+
+```ruby
+turns = PriorityMachines::WeightedRoundRobin.new(weights: [3, 1])
+Array.new(8) { turns.select([true, true]) }   # => [0, 0, 0, 1, 0, 0, 0, 1]
+```
+
+A lane that isn't ready is skipped, not saved up:
+
+```ruby
+turns = PriorityMachines::WeightedRoundRobin.new(weights: [3, 1])
+Array.new(4) { turns.select([false, true]) }  # => [1, 1, 1, 1]
+```
+
+Nothing ready anywhere returns `nil`. Weights are positive Integers, one to sixteen lanes.
+
+## Deficit Round Robin
+
+Each lane earns `quanta[lane]` credits per round. A lane is served when its credit covers the cost of its head job, and leftover credit carries forward. Pass the cost of the head job per lane, or `nil` for an empty lane.
+
+```ruby
+credit = PriorityMachines::DeficitRoundRobin.new(quanta: [3, 1])
+Array.new(8) { credit.select([1, 1]) }   # => [0, 0, 0, 1, 0, 0, 0, 1]
+```
+
+Same shape as weighted when every job costs one. Now make lane 0's jobs cost three:
+
+```ruby
+credit = PriorityMachines::DeficitRoundRobin.new(quanta: [4, 2])
+Array.new(6) { credit.select([3, 1]) }   # => [0, 1, 1, 0, 1, 1]
+```
+
+Lane 0 gets one heavy job per round. Lane 1 gets two light ones. Nobody starves, and the heavy lane can't buy extra turns by being heavy.
+
+If a lane drains, throw away what it had saved so it doesn't come back with a windfall:
+
+```ruby
+credit.deactivate(0)   # => true
+credit.deactivate(99)  # => false, no such lane
+```
+
+An empty lane is `nil`; costs are positive Integers.
+
+## Earliest Deadline First
+
+No state at all. Hand it one deadline per lane, as seconds on whatever monotonic clock you use, with `nil` for lanes that have nothing. Get back the lane with the nearest deadline, lowest index on a tie.
+
+```ruby
+PriorityMachines.earliest_deadline([10, nil, 0.25])   # => 2
+PriorityMachines.earliest_deadline([5, 5, 1])         # => 2
+PriorityMachines.earliest_deadline([nil, nil])        # => nil
+```
+
+Deadlines in the past still count. A job that is already late is the most urgent one you have.
+
+## The Rules of the Escort
+
+- **Lanes are one to sixteen.** Weights and quanta arrays set the lane count; every later call must pass an array of exactly that length or it raises `ArgumentError`.
+- **Weights, quanta and costs are positive Integers.** Floats raise `TypeError`. Zero raises `ArgumentError`. Negative or above 32 bits raises `RangeError`.
+- **Ready flags are real booleans.** Weighted round robin rejects anything that isn't `true` or `false`.
+- **Deadlines are finite, non-negative** Integers or Floats, or `nil`. NaN, infinity, and negatives raise `ArgumentError`.
+- **Bad input changes nothing.** The whole call is checked before any lane state moves.
+- **Frozen means frozen.** `freeze` a scheduler and `select` and `deactivate` raise `FrozenError`. `lane_count` still answers.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "I'll give the big customer a lower priority number."
+### Reality: Priority is a label. Fairness is a budget.
+
+A priority sorts the queue once. It says nothing about how much of the worker the top entry is allowed to consume before someone else gets a go. A budget does, and it remembers what was already spent. That's the difference between "high priority" and "three turns per round."
+
+## What's Yours
+
+The scheduler answers one question per call and remembers only what it needs for the next one. Your queues hold the jobs. Your code pops from the lane it points at and runs the job. Your clock supplies the deadlines. If several workers share one scheduler, wrap it in a lock. If you want a lane to stop earning credit, tell it with `deactivate`.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: The contact form was never low priority. It was just standing behind forty gigabytes.**

data/ext/priority_machines_native/core/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.3.2](https://github.com/seuros/priority_machines/compare/priority-machines-v0.3.1...priority-machines-v0.3.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([1d389af](https://github.com/seuros/priority_machines/commit/1d389af51eacb70fe595028c381c68cb9d556f51))
+
+## [0.3.1](https://github.com/seuros/priority_machines/compare/priority-machines-v0.3.0...priority-machines-v0.3.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([37e58c0](https://github.com/seuros/priority_machines/commit/37e58c0575a088807db99d38ea820d87dde956b8))
+
+## [0.3.0](https://github.com/seuros/priority_machines/compare/priority-machines-v0.2.0...priority-machines-v0.3.0) (2026-11-06)
+
+
+### Features
+
+* plain round robin scheduler in the core ([315e567](https://github.com/seuros/priority_machines/commit/315e5677ab93d677c71847233abcaa2bad5a7f4e))
+
+## [0.2.0](https://github.com/seuros/priority_machines/compare/priority-machines-v0.1.0...priority-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([ea040c3](https://github.com/seuros/priority_machines/commit/ea040c3e486d5b77a9eb4c68a8ac493399df8323))

data/ext/priority_machines_native/core/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "priority-machines"
+version = "0.3.2"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Allocation-free EDF, round robin, weighted round robin, and deficit round robin decisions"
+keywords = ["scheduling", "no-std", "priority", "round-robin", "edf"]
+categories = ["no-std", "algorithms"]
+readme = "README.md"
+exclude = ["src/**/tests.rs", "tests/"]
+[lints]
+workspace = true

data/ext/priority_machines_native/core/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PriorityMachines contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/ext/priority_machines_native/core/README.md

@@ -0,0 +1,125 @@
+# priority-machines
+
+> **AMS Liu**, NCC-4215, *Liu*-class dispatch escort.
+
+Engine-room flight manual: order departures by deadline, weight, or accounted cost.
+
+Allocation-free scheduling policies. No threads, I/O, wall clock, queue storage,
+allocator, or dependencies. The crate is always `no_std`.
+
+The caller supplies a view of eligible work; the scheduler returns an index.
+A successful selection **consumes a scheduling turn or cost credit**. Serialize
+selection with dequeue/admission in your adapter: this is not a reservation or
+an execution guarantee. Filter blocked and cancelled work before selecting.
+
+## Earliest Deadline First
+
+```rust
+use core::time::Duration;
+use priority_machines::earliest_deadline;
+
+let deadlines = [
+    Some(Duration::from_millis(30)),
+    None,
+    Some(Duration::from_millis(10)),
+];
+assert_eq!(earliest_deadline(&deadlines), Some(2));
+```
+
+Supply absolute deadlines as durations from one common monotonic origin.
+`None` means ineligible, not "best effort with no deadline". Equal deadlines
+choose the lowest index; order the input by arrival if FIFO ties are required.
+Overdue deadlines remain eligible: cancellation and deadline enforcement belong
+to the caller. This policy makes no preemption or schedulability guarantee.
+
+## Round Robin
+
+```rust
+use priority_machines::RoundRobin;
+
+let mut scheduler = RoundRobin::new();
+assert_eq!(scheduler.select(&[false, true, true]), Some(1));
+assert_eq!(scheduler.select(&[false, true, true]), Some(2));
+assert_eq!(scheduler.select(&[true, true]), Some(0));
+assert_eq!(scheduler.select(&[]), None);
+```
+
+The unweighted case with no fixed lane count. The `ready` slice sets the lanes
+on every call and the cursor wraps, so lanes may appear and vanish between
+calls. One `usize` of state.
+
+## Weighted Round Robin
+
+```rust
+use core::num::NonZeroU32;
+use priority_machines::WeightedRoundRobin;
+
+# fn example() -> Option<()> {
+let mut scheduler = WeightedRoundRobin::new([
+    NonZeroU32::new(2)?,
+    NonZeroU32::MIN,
+]);
+assert_eq!(
+    core::array::from_fn::<_, 6, _>(|_| scheduler.select(&[true, true])),
+    [Some(0), Some(0), Some(1), Some(0), Some(0), Some(1)],
+);
+# Some(())
+# }
+# assert_eq!(example(), Some(()));
+```
+
+This is **burst WRR**, not smooth WRR. Each continuously ready lane gets its
+positive weight in consecutive turns per cycle. It shares dispatch counts, not
+bytes or CPU time. Unready lanes forfeit unused turns; idle lanes cannot bank
+turns. Zero lanes are supported and select nothing.
+
+## Deficit Round Robin
+
+```rust
+use core::num::NonZeroU32;
+use priority_machines::DeficitRoundRobin;
+
+# fn example() -> Option<()> {
+let mut scheduler = DeficitRoundRobin::new([
+    NonZeroU32::new(4)?,
+    NonZeroU32::new(2)?,
+]);
+let heads = [NonZeroU32::new(2), NonZeroU32::new(2)];
+assert_eq!(
+    core::array::from_fn::<_, 6, _>(|_| scheduler.select(&heads)),
+    [Some(0), Some(0), Some(1), Some(0), Some(0), Some(1)],
+);
+# Some(())
+# }
+# assert_eq!(example(), Some(()));
+```
+
+Each lane receives a positive quantum per visit. A head consumes its positive
+cost from that lane's deficit. Remaining credit can serve more heads in the same
+visit; insufficient credit carries into the next round. Quanta and head costs
+must use the same unit, such as bytes or estimated work units.
+
+Pass the current head cost for each lane, or `None` for an empty lane, on every
+selection. Update your queues after dispatch. When a lane drains or is removed,
+call `deactivate(lane)` **before refilling it** so old credit cannot leak into a
+new busy period. Empty lanes observed during selection also lose their credit.
+WRR exposes the same lifecycle hook to relinquish unused turns immediately.
+
+Costs larger than a quantum still make progress. Entire unproductive rounds are
+skipped arithmetically: selection uses at most two lane scans, rather than
+looping once per unit of a large cost. Credits use `u64` internally for `u32`
+quanta/costs. Idle credit is not accumulated.
+
+Fairness is in accounted cost over continuously backlogged lanes, not in job
+counts or actual execution time. A bad cost estimate produces a bad resource
+share; this core does not measure or preempt work.
+
+## Integration Contract
+
+- Keep lane indices stable for the lifetime of a scheduler.
+- Weights, quanta, and lane count are fixed at construction. Construct a fresh
+  scheduler when changing them.
+- Selection is deterministic for the same initial state and input sequence.
+- Snapshot views and dispatch must be coordinated by the caller; the core adds
+  no locking.
+- No serialization format or Ruby binding is promised by this initial version.

data/ext/priority_machines_native/core/src/deficit.rs

@@ -0,0 +1,111 @@
+use core::num::NonZeroU32;
+
+/// Deficit round robin over fixed, caller-owned lanes with explicit head costs.
+///
+/// Positive quanta and costs use the same unit. Empty lanes lose their credit.
+/// Each successful selection charges one head; update the queue view before
+/// selecting again. This policy measures accounted work, not actual CPU time.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DeficitRoundRobin<const N: usize> {
+    quanta: [NonZeroU32; N],
+    deficits: [u64; N],
+    cursor: usize,
+    needs_quantum: bool,
+}
+
+impl<const N: usize> DeficitRoundRobin<N> {
+    /// Construct a scheduler with positive quanta and no accumulated credit.
+    #[must_use]
+    pub const fn new(quanta: [NonZeroU32; N]) -> Self {
+        Self {
+            quanta,
+            deficits: [0; N],
+            cursor: 0,
+            needs_quantum: true,
+        }
+    }
+
+    /// Charge and select the next affordable head.
+    ///
+    /// `None` marks an empty lane. Returns `None` exactly when all lanes are
+    /// empty. Expensive heads accumulate enough credit via skipped rounds in
+    /// O(N) time, using at most two selection scans.
+    pub fn select(&mut self, heads: &[Option<NonZeroU32>; N]) -> Option<usize> {
+        // Observe every empty lane, even if selection stops before visiting it.
+        for (deficit, head) in self.deficits.iter_mut().zip(heads) {
+            if head.is_none() {
+                *deficit = 0;
+            }
+        }
+        if let Some(lane) = self.select_round(heads) {
+            return Some(lane);
+        }
+
+        // Every active head is now unaffordable and every lane has been visited.
+        // Skip only whole rounds in which no head could have been dispatched.
+        let rounds = heads
+            .iter()
+            .enumerate()
+            .filter_map(|(lane, head)| {
+                head.map(|cost| {
+                    (u64::from(cost.get()) - self.deficits[lane])
+                        .div_ceil(u64::from(self.quanta[lane].get()))
+                })
+            })
+            .min()?;
+        let skipped = rounds - 1;
+        for (lane, head) in heads.iter().enumerate() {
+            if head.is_some() {
+                self.deficits[lane] += skipped * u64::from(self.quanta[lane].get());
+            }
+        }
+        self.select_round(heads)
+    }
+
+    /// Discard a lane's credit and end its current visit, if any.
+    ///
+    /// Call when a queue drains or is removed, before refilling that lane.
+    /// Returns `false` for an out-of-range index, without changing state.
+    pub const fn deactivate(&mut self, lane: usize) -> bool {
+        if lane >= N {
+            return false;
+        }
+        self.deficits[lane] = 0;
+        if lane == self.cursor {
+            self.advance();
+        }
+        true
+    }
+
+    fn select_round(&mut self, heads: &[Option<NonZeroU32>; N]) -> Option<usize> {
+        for _ in 0..N {
+            let lane = self.cursor;
+            if let Some(cost) = heads[lane] {
+                if self.needs_quantum {
+                    // An unsuccessful visit leaves deficit < cost <= u32::MAX.
+                    // Adding a u32 quantum therefore cannot overflow u64.
+                    self.deficits[lane] += u64::from(self.quanta[lane].get());
+                    self.needs_quantum = false;
+                }
+                if self.deficits[lane] >= u64::from(cost.get()) {
+                    self.deficits[lane] -= u64::from(cost.get());
+                    return Some(lane);
+                }
+            }
+            self.advance();
+        }
+        None
+    }
+
+    const fn advance(&mut self) {
+        self.cursor = if self.cursor + 1 == N {
+            0
+        } else {
+            self.cursor + 1
+        };
+        self.needs_quantum = true;
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/priority_machines_native/core/src/edf.rs

@@ -0,0 +1,19 @@
+use core::time::Duration;
+
+/// Select the lowest-index eligible item with the earliest deadline.
+///
+/// Deadlines must share one monotonic origin. `None` marks an ineligible item.
+/// Expired items are not automatically dropped. Returns `None` if no item is
+/// eligible, including when the input is empty. Runs in O(n) time.
+#[must_use]
+pub fn earliest_deadline(deadlines: &[Option<Duration>]) -> Option<usize> {
+    deadlines
+        .iter()
+        .enumerate()
+        .filter_map(|(index, deadline)| deadline.map(|value| (index, value)))
+        .min_by_key(|&(_, deadline)| deadline)
+        .map(|(index, _)| index)
+}
+
+#[cfg(test)]
+mod tests;

data/ext/priority_machines_native/core/src/lib.rs

@@ -0,0 +1,12 @@
+#![no_std]
+#![doc = include_str!("../README.md")]
+
+mod deficit;
+mod edf;
+mod round_robin;
+mod weighted;
+
+pub use deficit::DeficitRoundRobin;
+pub use edf::earliest_deadline;
+pub use round_robin::RoundRobin;
+pub use weighted::WeightedRoundRobin;

data/ext/priority_machines_native/core/src/round_robin.rs

@@ -0,0 +1,47 @@
+/// Plain round robin over however many lanes the caller has right now.
+///
+/// The lane count is the length of the `ready` slice on each call, so lanes may
+/// be added or removed between calls; the cursor wraps. All lanes weigh the
+/// same. The caller owns queue storage and execution.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct RoundRobin {
+    cursor: usize,
+}
+
+impl RoundRobin {
+    /// Construct a scheduler initially visiting lane zero.
+    #[must_use]
+    pub const fn new() -> Self {
+        Self { cursor: 0 }
+    }
+
+    /// The next ready lane at or after the cursor; the cursor moves past it.
+    ///
+    /// Returns `None` exactly when no lane is ready. O(N) worst case.
+    pub const fn select(&mut self, ready: &[bool]) -> Option<usize> {
+        let lanes = ready.len();
+        if lanes == 0 {
+            return None;
+        }
+        let mut lane = self.cursor % lanes;
+        let mut visited = 0;
+        while visited < lanes {
+            if ready[lane] {
+                self.cursor = if lane + 1 == lanes { 0 } else { lane + 1 };
+                return Some(lane);
+            }
+            lane = if lane + 1 == lanes { 0 } else { lane + 1 };
+            visited += 1;
+        }
+        None
+    }
+
+    /// Where the next search starts.
+    #[must_use]
+    pub const fn cursor(&self) -> usize {
+        self.cursor
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/priority_machines_native/core/src/weighted.rs

@@ -0,0 +1,69 @@
+use core::num::NonZeroU32;
+
+/// Burst weighted round robin over a fixed set of caller-owned lanes.
+///
+/// Weights count dispatches, not work cost. Empty lanes forfeit their remaining
+/// turns. The caller owns queue storage and execution.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WeightedRoundRobin<const N: usize> {
+    weights: [NonZeroU32; N],
+    cursor: usize,
+    remaining: u32,
+}
+
+impl<const N: usize> WeightedRoundRobin<N> {
+    /// Construct a scheduler with positive weights, initially visiting lane zero.
+    #[must_use]
+    pub const fn new(weights: [NonZeroU32; N]) -> Self {
+        Self {
+            remaining: if N == 0 { 0 } else { weights[0].get() },
+            weights,
+            cursor: 0,
+        }
+    }
+
+    /// Consume one turn from the next ready lane.
+    ///
+    /// Returns `None` exactly when no lane is ready. Runs in O(N) worst-case
+    /// time; repeated dispatches from the current lane take O(1).
+    pub fn select(&mut self, ready: &[bool; N]) -> Option<usize> {
+        for _ in 0..N {
+            let lane = self.cursor;
+            if ready[lane] {
+                self.remaining -= 1;
+                if self.remaining == 0 {
+                    self.advance();
+                }
+                return Some(lane);
+            }
+            self.advance();
+        }
+        None
+    }
+
+    /// Relinquish unused turns if this lane is currently being visited.
+    ///
+    /// Call when a queue drains or is removed, before reusing that lane.
+    /// Returns `false` for an out-of-range index, without changing state.
+    pub const fn deactivate(&mut self, lane: usize) -> bool {
+        if lane >= N {
+            return false;
+        }
+        if lane == self.cursor {
+            self.advance();
+        }
+        true
+    }
+
+    const fn advance(&mut self) {
+        self.cursor = if self.cursor + 1 == N {
+            0
+        } else {
+            self.cursor + 1
+        };
+        self.remaining = self.weights[self.cursor].get();
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/priority_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/ext/priority_machines_native/ffi/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "priority_machines_native"
+version = "0.1.4"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Thin native Ruby bindings for priority-machines"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+test = false
+doctest = false
+
+[dependencies]
+priority-machines.workspace = true
+magnus.workspace = true
+rb-sys.workspace = true
+
+[lints]
+workspace = true

data/ext/priority_machines_native/ffi/extconf.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'pathname'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('priority_machines_native/priority_machines_native') do |extension|
+  extension.ext_dir = Pathname(__dir__).relative_path_from(Pathname(Dir.pwd)).to_s
+  extension.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+end
+
+# rake-compiler builds from tmp/, not from the extension source directory.
+makefile = File.join(Dir.pwd, 'Makefile')
+File.write(makefile, File.read(makefile).gsub(
+  /^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/,
+  "RB_SYS_CARGO_MANIFEST_DIR ?= #{File.expand_path(__dir__)}"
+))

data/ext/priority_machines_native/ffi/src/init.rs

@@ -0,0 +1,8 @@
+use magnus::{Error, Ruby, function, prelude::*};
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("PriorityMachines")?;
+    module.define_singleton_method("earliest_deadline", function!(crate::earliest_deadline, 1))?;
+    crate::scheduler::define(ruby, module)
+}

data/ext/priority_machines_native/ffi/src/lib.rs

@@ -0,0 +1,62 @@
+//! Thin Ruby adapters; scheduling decisions belong exclusively to the core.
+
+mod init;
+mod scheduler;
+
+use std::{num::NonZeroU32, time::Duration};
+
+use magnus::{Error, Float, Integer, RArray, Ruby, TryConvert, Value, prelude::*};
+
+#[derive(Clone, Copy)]
+pub(crate) struct Count(pub(crate) u32);
+
+impl TryConvert for Count {
+    fn try_convert(value: Value) -> Result<Self, Error> {
+        let ruby = Ruby::get_with(value);
+        if Integer::from_value(value).is_none() {
+            return Err(Error::new(
+                ruby.exception_type_error(),
+                "expected an Integer",
+            ));
+        }
+        u32::try_convert(value).map(Self)
+    }
+}
+
+pub(crate) fn positive(ruby: &Ruby, value: Value) -> Result<NonZeroU32, Error> {
+    NonZeroU32::new(Count::try_convert(value)?.0)
+        .ok_or_else(|| Error::new(ruby.exception_arg_error(), "expected a positive u32"))
+}
+
+fn duration(ruby: &Ruby, value: Value) -> Result<Duration, Error> {
+    if Integer::from_value(value).is_some() {
+        return u64::try_convert(value).map(Duration::from_secs);
+    }
+    if Float::from_value(value).is_none() {
+        return Err(Error::new(
+            ruby.exception_type_error(),
+            "seconds must be Integer or Float",
+        ));
+    }
+    Duration::try_from_secs_f64(f64::try_convert(value)?).map_err(|_| {
+        Error::new(
+            ruby.exception_arg_error(),
+            "seconds must be finite, nonnegative and representable",
+        )
+    })
+}
+
+pub(crate) fn earliest_deadline(ruby: &Ruby, deadlines: RArray) -> Result<Option<usize>, Error> {
+    // Convert the complete call before entering the core.
+    let deadlines = deadlines
+        .into_iter()
+        .map(|value| {
+            if value.is_nil() {
+                Ok(None)
+            } else {
+                duration(ruby, value).map(Some)
+            }
+        })
+        .collect::<Result<Vec<_>, Error>>()?;
+    Ok(priority_machines::earliest_deadline(&deadlines))
+}

data/ext/priority_machines_native/ffi/src/scheduler.rs

@@ -0,0 +1,156 @@
+//! Exact const-generic lane counts, erased only at the Ruby boundary.
+
+use std::{cell::RefCell, num::NonZeroU32};
+
+use magnus::{
+    Error, RArray, RHash, RModule, Ruby, Value, function, method,
+    prelude::*,
+    scan_args::{get_kwargs, scan_args},
+    typed_data::Obj,
+};
+use priority_machines::{DeficitRoundRobin, WeightedRoundRobin};
+
+use crate::{Count, positive};
+
+// This trait erases const-generic sizes, never adds inactive/phantom lanes.
+trait Policy: Send {
+    fn select(&mut self, heads: &[Option<NonZeroU32>]) -> Option<usize>;
+    fn deactivate(&mut self, lane: usize) -> bool;
+}
+
+impl<const N: usize> Policy for WeightedRoundRobin<N> {
+    fn select(&mut self, heads: &[Option<NonZeroU32>]) -> Option<usize> {
+        self.select(&std::array::from_fn(|index| heads[index].is_some()))
+    }
+    fn deactivate(&mut self, lane: usize) -> bool {
+        self.deactivate(lane)
+    }
+}
+
+impl<const N: usize> Policy for DeficitRoundRobin<N> {
+    fn select(&mut self, heads: &[Option<NonZeroU32>]) -> Option<usize> {
+        self.select(&std::array::from_fn(|index| heads[index]))
+    }
+    fn deactivate(&mut self, lane: usize) -> bool {
+        self.deactivate(lane)
+    }
+}
+
+struct State {
+    policy: RefCell<Box<dyn Policy>>,
+    lanes: usize,
+}
+
+fn make(ruby: &Ruby, values: RArray, deficit: bool) -> Result<State, Error> {
+    let values = values
+        .into_iter()
+        .map(|value| positive(ruby, value))
+        .collect::<Result<Vec<_>, _>>()?;
+    macro_rules! sized {
+        ($($n:literal),*) => {
+            match values.len() {
+                $($n => {
+                    let array = std::array::from_fn::<_, $n, _>(|index| values[index]);
+                    if deficit { Box::new(DeficitRoundRobin::new(array)) as Box<dyn Policy> }
+                    else { Box::new(WeightedRoundRobin::new(array)) as Box<dyn Policy> }
+                },)*
+                _ => return Err(Error::new(ruby.exception_arg_error(), "lane count must be 1..16")),
+            }
+        };
+    }
+    let policy = sized!(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16);
+    Ok(State {
+        policy: RefCell::new(policy),
+        lanes: values.len(),
+    })
+}
+
+fn inputs(
+    ruby: &Ruby,
+    state: &State,
+    values: RArray,
+    deficit: bool,
+) -> Result<Vec<Option<NonZeroU32>>, Error> {
+    if values.len() != state.lanes {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "input length must match lane count",
+        ));
+    }
+    values
+        .into_iter()
+        .map(|value| {
+            if deficit {
+                if value.is_nil() {
+                    Ok(None)
+                } else {
+                    positive(ruby, value).map(Some)
+                }
+            } else if magnus::value::Qtrue::from_value(value).is_some() {
+                Ok(Some(NonZeroU32::MIN))
+            } else if magnus::value::Qfalse::from_value(value).is_some() {
+                Ok(None)
+            } else {
+                Err(Error::new(
+                    ruby.exception_type_error(),
+                    "ready entries must be true or false",
+                ))
+            }
+        })
+        .collect()
+}
+
+#[magnus::wrap(class = "PriorityMachines::WeightedRoundRobin", free_immediately, size)]
+struct Weighted(State);
+
+#[magnus::wrap(class = "PriorityMachines::DeficitRoundRobin", free_immediately, size)]
+struct Deficit(State);
+
+macro_rules! wrapper {
+    ($type:ident, $class:literal, $keyword:literal, $deficit:literal) => {
+        impl $type {
+            fn new(ruby: &Ruby, args: &[Value]) -> Result<Self, Error> {
+                let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
+                let (values,) =
+                    get_kwargs::<_, (RArray,), (), ()>(args.keywords, &[$keyword], &[])?.required;
+                make(ruby, values, $deficit).map(Self)
+            }
+            fn select(
+                ruby: &Ruby,
+                rb_self: Obj<Self>,
+                values: RArray,
+            ) -> Result<Option<usize>, Error> {
+                rb_self.check_frozen()?;
+                let values = inputs(ruby, &rb_self.0, values, $deficit)?;
+                let selected = rb_self.0.policy.borrow_mut().select(&values);
+                Ok(selected)
+            }
+            fn deactivate(rb_self: Obj<Self>, lane: Count) -> Result<bool, Error> {
+                rb_self.check_frozen()?;
+                let changed = rb_self.0.policy.borrow_mut().deactivate(lane.0 as usize);
+                Ok(changed)
+            }
+            const fn lane_count(&self) -> usize {
+                self.0.lanes
+            }
+        }
+    };
+}
+
+wrapper!(Weighted, "WeightedRoundRobin", "weights", false);
+wrapper!(Deficit, "DeficitRoundRobin", "quanta", true);
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), Error> {
+    macro_rules! register {
+        ($type:ident, $name:literal) => {{
+            let class = module.define_class($name, ruby.class_object())?;
+            class.define_singleton_method("new", function!($type::new, -1))?;
+            class.define_method("select", method!($type::select, 1))?;
+            class.define_method("deactivate", method!($type::deactivate, 1))?;
+            class.define_method("lane_count", method!($type::lane_count, 0))?;
+        }};
+    }
+    register!(Weighted, "WeightedRoundRobin");
+    register!(Deficit, "DeficitRoundRobin");
+    Ok(())
+}

data/lib/priority_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PriorityMachines
+  VERSION = '0.1.5'
+end

data/lib/priority_machines.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'priority_machines/version'
+require 'priority_machines_native/priority_machines_native'

data/sig/priority_machines.rbs

@@ -0,0 +1,18 @@
+module PriorityMachines
+  VERSION: String
+  def self.earliest_deadline: (Array[Integer | Float | nil] deadlines) -> Integer?
+
+  class WeightedRoundRobin
+    def self.new: (weights: Array[Integer]) -> instance
+    def select: (Array[bool] ready) -> Integer?
+    def deactivate: (Integer lane) -> bool
+    def lane_count: () -> Integer
+  end
+
+  class DeficitRoundRobin
+    def self.new: (quanta: Array[Integer]) -> instance
+    def select: (Array[Integer?] heads) -> Integer?
+    def deactivate: (Integer lane) -> bool
+    def lane_count: () -> Integer
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: priority_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: ruby
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: Thin Ruby binding to the standalone allocation-free priority-machines
+  Rust core. Initial, unstable local implementation; caller owns queues and execution.
+email:
+- oss@seuros.com
+executables: []
+extensions:
+- ext/priority_machines_native/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- ext/priority_machines_native/core/CHANGELOG.md
+- ext/priority_machines_native/core/Cargo.toml
+- ext/priority_machines_native/core/LICENSE
+- ext/priority_machines_native/core/README.md
+- ext/priority_machines_native/core/src/deficit.rs
+- ext/priority_machines_native/core/src/edf.rs
+- ext/priority_machines_native/core/src/lib.rs
+- ext/priority_machines_native/core/src/round_robin.rs
+- ext/priority_machines_native/core/src/weighted.rs
+- ext/priority_machines_native/extconf.rb
+- ext/priority_machines_native/ffi/Cargo.toml
+- ext/priority_machines_native/ffi/extconf.rb
+- ext/priority_machines_native/ffi/src/init.rs
+- ext/priority_machines_native/ffi/src/lib.rs
+- ext/priority_machines_native/ffi/src/scheduler.rs
+- lib/priority_machines.rb
+- lib/priority_machines/version.rb
+- sig/priority_machines.rbs
+homepage: https://github.com/seuros/priority_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/priority_machines
+  bug_tracker_uri: https://github.com/seuros/priority_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: priority_machines_native
+  cargo_manifest_path: ext/priority_machines_native/ffi/Cargo.toml
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Native deadline, weighted and deficit scheduling policies
+test_files: []