arbiter_machines 0.1.5-aarch64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ec1cc02077cd0a3484e47dec1d2bfe3139db4b295f2a083322404bb476c2462
+  data.tar.gz: d364fa500c077c33a03f80615e857fb45e75b9e8cfec8a814a24783c6d1de895
+SHA512:
+  metadata.gz: 7b7ad6b35d3e98b4e9bbf712334186db2642e129d5c31be9b819ea672f4b21784d3ac1d387af65895a1a1a5700e3ebae03814de42eb1df2dbdc052c73955a850
+  data.tar.gz: 484ab97b811be4da0aca64ec75fcf920a722bac9c18e611759fe437aa69a1fe880eca425c95b852e027718c1a4fd198c5f5e5895e8740de1e38c3d0964452011

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.1.5](https://github.com/seuros/arbiter_machines/compare/arbiter_machines/v0.1.4...arbiter_machines/v0.1.5) (2026-11-06)
+
+
+### Bug Fixes
+
+* share RArray count conversion in arbiter ffi ([0a026aa](https://github.com/seuros/arbiter_machines/commit/0a026aac2e17efecc2546bb8b9532b89f516e7f0))
+
+## [0.1.4](https://github.com/seuros/arbiter_machines/compare/arbiter_machines/v0.1.3...arbiter_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([10c8cad](https://github.com/seuros/arbiter_machines/commit/10c8cad0f35cb6c44dbe0e5573275f2267afc306))
+
+## [0.1.3](https://github.com/seuros/arbiter_machines/compare/arbiter_machines/v0.1.2...arbiter_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([513f507](https://github.com/seuros/arbiter_machines/commit/513f5074a2058f23742ee47b2289cd8b8872d6d3))
+
+## [0.1.2](https://github.com/seuros/arbiter_machines/compare/arbiter_machines/v0.1.1...arbiter_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* cross builds no longer compile for the host ([feeb4f0](https://github.com/seuros/arbiter_machines/commit/feeb4f09e5d0b20b81a3fffb35562594b80e2e0a))
+
+## [0.1.1](https://github.com/seuros/arbiter_machines/compare/arbiter_machines-v0.1.0...arbiter_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([0ce828b](https://github.com/seuros/arbiter_machines/commit/0ce828bfacd5c9ef7482136b73d7be18339e19b9))

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,221 @@
+# ArbiterMachines
+
+> When the slow job holds the key the urgent job needs, more workers won't help. 🛰️
+
+A priority arbiter for Ruby. You declare your tasks with their priorities and your resources with their ceilings. The `Arbiter` tells you who may take what, who has to wait, who just inherited someone else's urgency, and who is about to deadlock. Your code still takes and releases the actual locks. The arbiter only ever answers one question: is this a good idea right now?
+
+## Quick Start
+
+```bash
+gem 'arbiter_machines'
+```
+
+```ruby
+# Two tasks: a janitor at priority 1, a payment at priority 10.
+# One resource: the ledger lock, ceiling 10.
+arbiter = ArbiterMachines::Arbiter.new(
+  priorities: [1, 10],
+  ceilings: [10],
+  protocol: :inheritance
+)
+
+arbiter.acquire(task: 0, resource: 0)   # => [:granted, nil]   janitor takes the ledger
+arbiter.acquire(task: 1, resource: 0)   # => [:blocked, 0]     payment waits on resource 0
+arbiter.effective_priorities            # => [10, 10]          janitor now runs as urgent
+
+arbiter.release(task: 0, resource: 0)   # => true              janitor done, wait cleared
+arbiter.acquire(task: 1, resource: 0)   # => [:granted, nil]   payment retries and gets in
+```
+
+Tasks and resources are positional indices into the arrays you passed in. Larger number means more urgent.
+
+## A Message to the Resistance
+
+So you gave the nightly cleanup job priority 1, the payment processor priority 10, and a pile of report builders priority 5. Sensible. Then one night the cleanup job took the ledger lock for a quick vacuum, the payment job arrived and blocked on it, and twelve report builders showed up and ran. All of them. Before the cleanup job got another slice of CPU.
+
+The payment job, your most urgent work, sat behind priority-5 reports because a priority-1 job was holding its lock and nobody told the scheduler that the priority-1 job was suddenly very important.
+
+That's priority inversion. It put a rover on Mars into a reboot loop in 1997, and it's been quietly doing the same thing to job queues ever since. The fix has been known just as long: while the janitor holds something the payment job needs, the janitor *is* the payment job. It inherits the urgency, finishes fast, hands the lock over.
+
+This gem does the accounting for that. Who holds what, who waits on whom, what everybody's priority really is right now, and whether the next acquire closes a loop nobody can escape from.
+
+## Chapter 1: Stardate 2025.186, the AMS Dijkstra
+
+> **AMS Dijkstra**, NCC-4201, *Dijkstra*-class traffic-control vessel.
+> One airlock. Two waiting crews. No circular holding pattern.
+
+The vessel doesn't open airlocks. It keeps the chart: which crew is in which lock, which crew is waiting at which door, and which crew's urgency has been lent to the crew blocking it. Before any crew is cleared to wait, the chart is checked for a loop. A loop is never charted, because a charted loop is a ship nobody leaves.
+
+Somewhere on the bridge, a junior officer suggests:
+
+```ruby
+def process_payment
+  ledger_lock.synchronize do   # the janitor has this, and the janitor is slow
+    charge_card
+  end
+end
+```
+
+"That," says the traffic controller, "is how urgent work waits for the floor to be mopped."
+
+## The Flight Plan
+
+Every resource is either free or held. Every task is either running, holding, or waiting at exactly one door.
+
+```mermaid
+stateDiagram-v2
+    [*] --> free
+    free --> held: acquire, granted
+    held --> held: holder acquires again, already_owned
+    held --> held: other task acquires, blocked (holder inherits urgency)
+    held --> free: holder releases, waiters cleared to retry
+    held --> held: acquire would close a wait loop, deadlock (nothing changes)
+    free --> [*]
+```
+
+And the night the janitor held the ledger:
+
+```mermaid
+sequenceDiagram
+    participant J as Janitor (task 0, prio 1)
+    participant A as Arbiter
+    participant P as Payment (task 1, prio 10)
+
+    J->>A: acquire(task 0, resource 0)
+    A-->>J: granted
+    Note over J: starts vacuuming the ledger
+
+    P->>A: acquire(task 1, resource 0)
+    A-->>P: blocked on resource 0
+    Note over A: effective priorities now [10, 10]
+    Note over J: runs as priority 10, no report builder gets ahead
+
+    J->>A: release(task 0, resource 0)
+    A-->>J: true
+    Note over A: effective priorities back to [1, 10], wait cleared
+
+    P->>A: acquire(task 1, resource 0)
+    A-->>P: granted
+```
+
+## How Arbitration Works
+
+### Acquire
+
+`acquire` returns a two-element array: a status and, when blocked, the resource index you're waiting on.
+
+```ruby
+arbiter = ArbiterMachines::Arbiter.new(
+  priorities: [1, 5, 10], ceilings: [10, 10], protocol: :inheritance
+)
+
+arbiter.acquire(task: 0, resource: 0)   # => [:granted, nil]
+arbiter.acquire(task: 0, resource: 0)   # => [:already_owned, nil]
+arbiter.acquire(task: 1, resource: 1)   # => [:granted, nil]
+arbiter.acquire(task: 1, resource: 0)   # => [:blocked, 0]
+```
+
+Task 1 now holds resource 1 and is waiting on resource 0, which task 0 holds.
+
+### Inheritance is transitive
+
+Urgency flows up the chain. If a third task waits on task 1, task 1 gets its priority, and so does task 0 behind it.
+
+```ruby
+arbiter.acquire(task: 2, resource: 1)   # => [:blocked, 1]
+arbiter.effective_priorities            # => [10, 10, 10]
+```
+
+Task 2, priority 10, waits on task 1. Task 1 waits on task 0. Everybody in the chain runs at 10 until the chain clears.
+
+### Release and retry
+
+Releasing clears the waits on that resource. It does not hand the resource to anyone. The waiters call `acquire` again, and the arbiter decides fresh.
+
+```ruby
+arbiter.release(task: 0, resource: 0)   # => true
+arbiter.effective_priorities            # => [1, 10, 10]  task 1 still blocks task 2
+arbiter.acquire(task: 1, resource: 0)   # => [:granted, nil]
+```
+
+Release by a task that doesn't hold the resource returns `false` and changes nothing.
+
+### Stop waiting
+
+A task that gives up on a door calls `cancel_wait`. Its held resources stay held. Only the wait is dropped, and the urgency it was lending goes with it.
+
+```ruby
+arbiter = ArbiterMachines::Arbiter.new(
+  priorities: [1, 5, 10], ceilings: [10, 10], protocol: :inheritance
+)
+arbiter.acquire(task: 0, resource: 0)
+arbiter.acquire(task: 2, resource: 0)   # => [:blocked, 0]
+arbiter.effective_priorities            # => [10, 5, 10]
+
+arbiter.cancel_wait(task: 2)            # => true
+arbiter.effective_priorities            # => [1, 5, 10]
+```
+
+### Deadlock is refused, not reported after the fact
+
+Two tasks each holding what the other wants is a loop. The arbiter sees it before charting the second wait and returns `:deadlock`. Nothing about the current state changes, so you can back out cleanly.
+
+```ruby
+arbiter = ArbiterMachines::Arbiter.new(
+  priorities: [1, 5, 10], ceilings: [10, 10], protocol: :inheritance
+)
+arbiter.acquire(task: 0, resource: 0)
+arbiter.acquire(task: 1, resource: 1)
+arbiter.acquire(task: 0, resource: 1)   # => [:blocked, 1]
+arbiter.acquire(task: 1, resource: 0)   # => [:deadlock, nil]
+arbiter.effective_priorities            # => [1, 5, 10]  untouched
+
+arbiter.cancel_wait(task: 0)            # => true, task 0 backs off
+arbiter.acquire(task: 1, resource: 0)   # => [:blocked, 0]  now it's a plain wait
+```
+
+### The other protocol: immediate ceiling
+
+With `:immediate_ceiling`, a task jumps to the resource's ceiling the moment it takes the resource, before anyone has to wait. Nobody with a priority at or below the ceiling can get in behind it.
+
+```ruby
+arbiter = ArbiterMachines::Arbiter.new(
+  priorities: [1, 5, 10], ceilings: [8, 10], protocol: :immediate_ceiling
+)
+arbiter.acquire(task: 0, resource: 0)   # => [:granted, nil]
+arbiter.effective_priorities            # => [8, 5, 10]   task 0 raised to the ceiling
+arbiter.acquire(task: 1, resource: 1)   # => [:blocked, 0] priority 5 can't clear a ceiling of 8
+arbiter.acquire(task: 2, resource: 1)   # => [:granted, nil] priority 10 can
+```
+
+A ceiling has to be at least as high as every task that will ever take the resource. Task 2 at priority 10 asking for resource 0 with ceiling 8 is a misdeclaration, and the arbiter says so:
+
+```ruby
+arbiter.acquire(task: 2, resource: 0)   # => [:invalid, nil]
+```
+
+## The Rules of the Vessel
+
+- **Up to 8 tasks and 8 resources**, chosen independently by the lengths of `priorities:` and `ceilings:`. Empty or longer arrays raise `ArgumentError`.
+- **Priorities, ceilings, and indices are non-negative Integers** below `2**32`. Floats and strings raise `TypeError`, out-of-range raises `RangeError`.
+- **Out-of-range task or resource indices** in `acquire` return `[:invalid, nil]`. In `cancel_wait` they return `false`. Nothing raises for a bad index, only for a bad type.
+- **`effective_priorities` is a fresh Array** every call. Mutate it all you like, the arbiter doesn't care.
+- **Frozen means frozen.** `freeze` the arbiter and `acquire`, `release`, and `cancel_wait` raise `FrozenError`. Reads still work.
+- **Ceilings are always required**, even under `:inheritance`, where they're not consulted.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "Priority 10 means it runs first."
+### Reality: Priority 10 means it waits first, behind whoever holds its lock.
+
+A priority is a promise about scheduling, not about locks. The moment a high-priority task blocks on a lock held by a low-priority one, every medium task in the system is effectively more urgent than your most urgent work. Inheritance is what makes the number mean something again.
+
+## What's Yours
+
+The arbiter never touches a mutex, a thread, or a scheduler. When it says `:granted`, you take the lock. When it says `:blocked`, you wait however you wait, then ask again after the holder releases. When it reports an effective priority, you're the one who has to tell your scheduler. Keep one arbiter per group of resources, and keep its calls serialized.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: Nobody can hear the payment job scream while the janitor mops at priority 1.**

data/ext/arbiter_machines_native/core/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.2](https://github.com/seuros/arbiter_machines/compare/arbiter-machines-v0.2.1...arbiter-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([10c8cad](https://github.com/seuros/arbiter_machines/commit/10c8cad0f35cb6c44dbe0e5573275f2267afc306))
+
+## [0.2.1](https://github.com/seuros/arbiter_machines/compare/arbiter-machines-v0.2.0...arbiter-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([513f507](https://github.com/seuros/arbiter_machines/commit/513f5074a2058f23742ee47b2289cd8b8872d6d3))
+
+## [0.2.0](https://github.com/seuros/arbiter_machines/compare/arbiter-machines-v0.1.0...arbiter-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([0ce828b](https://github.com/seuros/arbiter_machines/commit/0ce828bfacd5c9ef7482136b73d7be18339e19b9))

data/ext/arbiter_machines_native/core/README.md

@@ -0,0 +1,20 @@
+# arbiter-machines
+
+> **AMS Dijkstra**, NCC-4201, *Dijkstra*-class traffic-control vessel.
+
+Engine-room flight manual: coordinate airlock ownership without a circular wait.
+
+Allocation-free `no_std` ownership and wait-for decisions for fixed tasks/resources.
+Larger numeric priority means higher priority. One outstanding wait per task;
+nonrecursive ownership. Releases wake affected waiters to retry but never silently
+transfer ownership.
+
+Inheritance propagates priorities transitively to owners. Immediate-ceiling mode
+raises owners to held-resource ceilings and blocks acquisition unless effective
+priority exceeds every ceiling held by another task. Each configured resource
+ceiling must bound all tasks permitted to use it; requests exceeding it reject.
+The core detects prospective wait-for cycles before inserting a wait.
+
+These decisions require an executor honoring priorities and ownership. No OS
+priority manipulation, lock implementation, waiter-queue fairness, preemption
+driver, multi-resource atomic acquisition, or Ruby scheduling guarantee.

data/ext/arbiter_machines_native/extconf.rb

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

data/lib/arbiter_machines/version.rb

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

data/lib/arbiter_machines.rb

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

data/sig/arbiter_machines.rbs

@@ -0,0 +1,12 @@
+module ArbiterMachines
+  VERSION: String
+  class Arbiter
+    def self.new: (priorities: Array[Integer], ceilings: Array[Integer], protocol: :inheritance | :immediate_ceiling) -> instance
+    def acquire: (task: Integer, resource: Integer) -> [Symbol, Integer?]
+    def release: (task: Integer, resource: Integer) -> bool
+    def cancel_wait: (task: Integer) -> bool
+    def effective_priorities: () -> Array[Integer]
+    def task_count: () -> Integer
+    def resource_count: () -> Integer
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: arbiter_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: aarch64-linux
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: Thin Ruby adapter to the standalone allocation-free arbiter-machines
+  Rust core. Initial unstable local implementation; caller enforces all decisions.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/arbiter_machines_native/core/CHANGELOG.md
+- ext/arbiter_machines_native/core/README.md
+- ext/arbiter_machines_native/extconf.rb
+- lib/arbiter_machines.rb
+- lib/arbiter_machines/version.rb
+- lib/arbiter_machines_native/arbiter_machines_native.so
+- sig/arbiter_machines.rbs
+homepage: https://github.com/seuros/arbiter_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/arbiter_machines
+  bug_tracker_uri: https://github.com/seuros/arbiter_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: arbiter_machines_native
+  cargo_manifest_path: ext/arbiter_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: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Native bounded priority inheritance and resource ceiling decisions
+test_files: []