priority_machines 0.1.5-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bafce6c8f7f5ab703eb5f82e5777f6611a030f4da3b0525a1add498b44a55658
+  data.tar.gz: 7aef1746e644089f9d227eb1f4a9aac9d444c142b00502f5399046cfc604fade
+SHA512:
+  metadata.gz: 6418fb49e6e3fbebdd00f9434794ffa65c5f37268656ca0c1f42cda637b0cb60fb5366fafcc456878de9c6455c7b422e078d870efe422b50a8243bf417320adc
+  data.tar.gz: 64a56bf675274d8e5cc2d6f8af4bc6f2d7fff1e4a819fa737ba7ae976b3a25d009efe03d8cb0ecd83bc5ed3ae4782906700a780e81cb5d478d3b8648023f6f58

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/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/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/extconf.rb

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

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,63 @@
+--- !ruby/object:Gem::Specification
+name: priority_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: x86_64-linux-musl
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+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: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/priority_machines_native/core/CHANGELOG.md
+- ext/priority_machines_native/core/LICENSE
+- ext/priority_machines_native/core/README.md
+- ext/priority_machines_native/extconf.rb
+- lib/priority_machines.rb
+- lib/priority_machines/version.rb
+- lib/priority_machines_native/priority_machines_native.so
+- 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
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.22
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Native deadline, weighted and deficit scheduling policies
+test_files: []