pool_machines 0.1.3-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c6b296aef106fc0885f643bf602d08fa77556c3c9bbb14eb7e38dc8a91598ad2
+  data.tar.gz: 1da98319728442f71015117a4388d79a3a7d7f4fbe60330165459a393db88e27
+SHA512:
+  metadata.gz: c72dde4e1bf389cdbc1cab774ff4ff3f8b26024c1a67345b9a3b892cbde3e0ac6e59b339dfa8572fb985098b6eeafe28d42091c1b9126eb435088fd458702023
+  data.tar.gz: a003c86e00f9537b228aa47996506c6fe9b91c72658c918472fb6f65e0f93926c1c1472e7e6a2857eb27b917d58448d86711d618ee7b0d0cfdede80ff03028fd

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.1.3](https://github.com/seuros/pool_machines/compare/pool_machines/v0.1.2...pool_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([e65b159](https://github.com/seuros/pool_machines/commit/e65b1592ae2868c0acea23df562fab5b43dab71f))
+
+## [0.1.2](https://github.com/seuros/pool_machines/compare/pool_machines/v0.1.1...pool_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([d256e29](https://github.com/seuros/pool_machines/commit/d256e29c8cb52218216e7c796057a7fef3205b00))
+
+## [0.1.1](https://github.com/seuros/pool_machines/compare/pool_machines-v0.1.0...pool_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([030ecb6](https://github.com/seuros/pool_machines/commit/030ecb6977a3559cd397225ab2d38137a46d39b7))

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+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,218 @@
+# PoolMachines
+
+> A connection returned twice is a connection somebody else is now using. 🛠️
+
+A resource pool ledger for Ruby. You register the slots you've built, check them out, check them in, and ask which idle ones are old enough to tear down. The `Pool` never opens a socket or closes a file. It keeps the roster: which slot is busy, which is idle and since when, and whether the handle you just returned is the one it issued or a stale copy from an earlier trip.
+
+## Quick Start
+
+```bash
+gem 'pool_machines'
+```
+
+```ruby
+pool = PoolMachines::Pool.new
+now  = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) }
+
+# You build the connection. The pool just learns that slot 0 is serviceable.
+connections[0] = PG.connect(db_url)
+pool.register(0, now.call)         # => true
+
+# Each request borrows a slot and gives it back.
+handle = pool.checkout(now.call)   # => PoolMachines::Handle, or nil when none is free
+connections[handle.slot].exec(sql)
+pool.checkin(handle, now.call)     # => "idle"
+
+# On a quiet night, tear down whatever has sat idle for five minutes.
+while (slot = pool.retire_idle(now.call, 5 * 60 * 1_000_000_000))
+  connections.delete(slot).close
+end
+```
+
+Times are nanoseconds from a monotonic clock. Slots are the integers 0 through 31.
+
+## A Message to the Resistance
+
+So you wrote a connection pool. Everyone has. An array of connections, a mutex, `pop` on the way out, `push` on the way back. It worked for a year.
+
+Then a request timed out mid-query, the rescue block pushed the connection back, the ensure block pushed it back again, and for the next six hours two threads shared one socket. The errors made no sense because the errors belonged to someone else's query.
+
+The bug isn't the array. The bug is that a bare connection object can't tell you whether it's already been returned. The thing you push back has to carry a receipt, and the pool has to refuse a receipt it has already stamped. This gem is the receipt book. Your connections stay yours.
+
+## Chapter 1: Stardate 2025.186, the AMS Little
+
+> **AMS Little**, NCC-4214, *Little*-class service tender.
+> Do not fabricate a new warp core for every departure.
+
+The tender doesn't build engines. It keeps the dock roster: thirty-two bays, which are occupied, which hold a serviced core waiting for a ship, and how long each has waited. A crew that brings a core back gets a fresh bay ticket. A crew that turns up with last week's ticket is turned away, because that bay has been issued to someone else since.
+
+Somewhere on the dock, a cadet proposes:
+
+```ruby
+def with_connection
+  conn = @free.pop || PG.connect(db_url)
+  yield conn
+rescue => e
+  @free.push(conn)   # give it back on error
+  raise
+ensure
+  @free.push(conn)   # and also give it back always
+end
+```
+
+"That," says the dockmaster, "is how two ships leave on one core."
+
+## The Flight Plan
+
+Every slot is in exactly one state. Draining is a property of the whole pool.
+
+```mermaid
+stateDiagram-v2
+    [*] --> vacant
+    vacant --> idle: register(slot, now)
+    idle --> busy: checkout(now) issues a handle
+    busy --> idle: checkin(handle, now) returns "idle"
+    busy --> vacant: checkin while draining returns "retire"
+    idle --> vacant: retire_idle(now, idle_for) picks it
+    vacant --> idle: register again, same slot, fresh generation
+```
+
+And the deploy where the old pool was drained:
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant Pool
+    participant DB as Connections
+
+    App->>Pool: register(0, t0)
+    App->>Pool: register(1, t0)
+    App->>Pool: checkout(t1)
+    Pool-->>App: handle for slot 0
+    Note over App: query in flight on slot 0
+
+    Note over App: SIGTERM, deploy starting
+    App->>Pool: begin_drain
+    App->>Pool: checkout(t2)
+    Pool-->>App: nil, no new departures
+    App->>Pool: retire_idle(t2, any)
+    Pool-->>App: 1
+    App->>DB: close connection 1
+
+    App->>Pool: checkin(handle, t3)
+    Pool-->>App: "retire"
+    App->>DB: close connection 0
+    Note over Pool: checked_out is 0. Dock is empty.
+```
+
+## How the Dock Works
+
+### Register and check out
+
+```ruby
+pool = PoolMachines::Pool.new
+pool.checkout(0)          # => nil, nothing registered yet
+
+pool.register(0, 1)       # => true
+pool.register(0, 1)       # => false, already on the roster
+
+handle = pool.checkout(2)
+handle.slot               # => 0
+pool.checked_out          # => 1
+```
+
+`checkout` returns `nil` when every registered slot is busy. It never blocks and never builds anything. If you want to grow the pool, build a resource and `register` a free slot number.
+
+### Check in, and the receipt that only works once
+
+A handle is good for exactly one `checkin`. Return it and the slot goes idle. Return it again and the pool raises, because the slot may already belong to a newer handle.
+
+```ruby
+pool = PoolMachines::Pool.new
+pool.register(0, 1)
+
+first = pool.checkout(2)
+pool.checkin(first, 3)    # => "idle"
+
+second = pool.checkout(4) # same slot 0, new receipt
+pool.checkin(first, 5)    # raises ArgumentError, that receipt is spent
+pool.checkin(second, 5)   # => "idle"
+```
+
+That's the double-push bug from the cadet's code, caught at the second push instead of six hours later.
+
+### Retire what's been sitting
+
+`retire_idle` hands you one slot per call: an idle slot that has been idle for at least `idle_for` nanoseconds. It returns `nil` when nothing qualifies. Loop until `nil`, closing as you go.
+
+```ruby
+pool = PoolMachines::Pool.new
+pool.register(0, 0)
+pool.register(1, 0)
+
+pool.retire_idle(2, 3)    # => nil, idle for 2, needs 3
+pool.retire_idle(10, 5)   # => 0
+pool.retire_idle(10, 5)   # => 1
+pool.retire_idle(10, 5)   # => nil
+
+pool.register(0, 11)      # => true, the slot is vacant again
+```
+
+A busy slot is never retired. The pool will tell you to close it when it comes back.
+
+### Drain
+
+`begin_drain` flips the pool into wind-down. No more registrations, no more checkouts. Idle slots retire regardless of how long they've been idle. Busy slots keep working, and when each one is checked in the answer is `"retire"` instead of `"idle"`, which is your cue to close it.
+
+```ruby
+pool = PoolMachines::Pool.new
+pool.register(0, 0)
+pool.register(1, 0)
+handle = pool.checkout(1)
+
+pool.begin_drain
+pool.checkout(3)          # => nil
+pool.register(2, 3)       # => false
+pool.retire_idle(3, 100)  # => 1, idle_for is ignored while draining
+pool.checkin(handle, 4)   # => "retire"
+pool.checked_out          # => 0
+```
+
+Drain never yanks a resource out from under a running query. It only refuses new work and tells you what to close as work finishes.
+
+### The clock only moves forward
+
+You pass `now` on every call. The pool remembers the latest time it has seen and treats anything earlier as a non-event: `register` returns `false`, `checkout` returns `nil`, `checkin` raises.
+
+```ruby
+pool = PoolMachines::Pool.new
+pool.register(0, 5)
+pool.register(1, 3)       # => false, time went backwards
+```
+
+Use a monotonic clock. Wall clocks jump.
+
+## The Rules of the Tender
+
+- **32 slots, numbered 0 to 31.** Slot 32 or a negative slot raises `RangeError`.
+- **Every number is an Integer.** Slots, times, and durations. Floats, strings, and NaN raise `TypeError`. Values at or above `2**64` raise `RangeError`.
+- **Handles are opaque and single-use.** You can't construct one, `dup` one, or hand one to a different pool. A spent or foreign handle raises `ArgumentError` on `checkin`.
+- **Rejections are quiet, misuse is loud.** A duplicate `register`, a backwards clock, or an empty pool returns `false` or `nil`. A bad handle or a bad type raises.
+- **Frozen means frozen.** `freeze` the pool and every mutating call raises `FrozenError`. `checked_out` still answers.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "The ensure block guarantees the connection goes back."
+### Reality: The ensure block guarantees it goes back at least once.
+
+`ensure` runs after `rescue`. If both return the connection, it's returned twice, and a plain array can't tell. A pool that issues receipts can, and refuses the second one on the spot.
+
+## What's Yours
+
+The pool holds slot numbers and timestamps, nothing else. You create the real resource before `register`, keep it somewhere indexed by slot, and close it when `retire_idle` or a `"retire"` check-in says so. Health checks, waiting for a free slot, and persistence across restarts are all outside the roster. Serialize calls to one pool; it doesn't lock for you.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: The second `push` always looks harmless. The receipt book is what makes it fail where you can see it.**

data/ext/pool_machines_native/core/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.2](https://github.com/seuros/pool_machines/compare/pool-machines-v0.2.1...pool-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([e65b159](https://github.com/seuros/pool_machines/commit/e65b1592ae2868c0acea23df562fab5b43dab71f))
+
+## [0.2.1](https://github.com/seuros/pool_machines/compare/pool-machines-v0.2.0...pool-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([d256e29](https://github.com/seuros/pool_machines/commit/d256e29c8cb52218216e7c796057a7fef3205b00))
+
+## [0.2.0](https://github.com/seuros/pool_machines/compare/pool-machines-v0.1.0...pool-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([030ecb6](https://github.com/seuros/pool_machines/commit/030ecb6977a3559cd397225ab2d38137a46d39b7))

data/ext/pool_machines_native/core/README.md

@@ -0,0 +1,18 @@
+# pool-machines
+
+> **AMS Little**, NCC-4214, *Little*-class service tender.
+
+Engine-room flight manual: track resource checkouts, returns, and retirement.
+
+Allocation-free `no_std` lifecycle decisions for fixed resource slots.
+Register externally created resources, check out the oldest idle slot, and return
+it with a generation-checked handle. Duplicate/stale returns are rejected.
+Begin draining to refuse new checkouts; returned resources then retire rather
+than becoming idle. Idle retirement frees a slot for external destruction.
+
+Clock observations must not regress. Generations fail closed at exhaustion.
+Handles are scoped to one pool instance/lifetime; do not exchange handles between
+pools. The adapter must serialize these decisions with resource storage and
+actually destroy retired resources. There is no automatic construction, health
+check, async waiting, timeout driver, forced reclamation of busy resources,
+or runtime ownership guarantee.

data/ext/pool_machines_native/extconf.rb

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

data/lib/pool_machines/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module PoolMachines
+  VERSION = '0.1.3'
+end

data/lib/pool_machines.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+require_relative 'pool_machines/version'
+require 'pool_machines_native/pool_machines_native'

data/sig/pool_machines.rbs

@@ -0,0 +1,16 @@
+module PoolMachines
+  VERSION: String
+  # Opaque checkout result; direct construction is unsupported.
+  class Handle
+    def slot: () -> Integer
+  end
+  class Pool
+    def self.new: () -> instance
+    def register: (Integer slot, Integer now_ns) -> bool
+    def checkout: (Integer now_ns) -> Handle?
+    def checkin: (Handle handle, Integer now_ns) -> String
+    def begin_drain: () -> nil
+    def retire_idle: (Integer now_ns, Integer idle_for_ns) -> Integer?
+    def checked_out: () -> Integer
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: pool_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: x86_64-linux-musl
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: Initial native roster model with draining and retirement. Caller owns
+  resources and execution. Local sibling Rust checkout required.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/pool_machines_native/core/CHANGELOG.md
+- ext/pool_machines_native/core/README.md
+- ext/pool_machines_native/extconf.rb
+- lib/pool_machines.rb
+- lib/pool_machines/version.rb
+- lib/pool_machines_native/pool_machines_native.so
+- sig/pool_machines.rbs
+homepage: https://github.com/seuros/pool_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/pool_machines
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: pool_machines_native
+  cargo_manifest_path: ext/pool_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 generation-checked resource-slot policy for Ruby
+test_files: []