cache_machines 0.1.4-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5de5923202ed1cfbf5e7b10f664f3ed736850e8a9f3444c3b9a311f387a551c2
+  data.tar.gz: 1293d3d7baca19f73d4657c399d7bc5db652dea41c19275f5c2fd12e201fe276
+SHA512:
+  metadata.gz: aa7ae7af9f4de08fb00be5fb261390f66a5af4d98dbd002453eb41a1a6c80f7f603f969929cb8822a3505d594947cb3f658a773357dcd68a61f1fe1d329d7917
+  data.tar.gz: 15a9dd3d80bd26916738c9f40f137939a646a171d5fb5bdaa335163114ed1a4f927f83fed19c0a06dafa6ff3f42517b6e4dffab188c89d4a4e9f7b6c03707f05

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.1.4](https://github.com/seuros/cache_machines/compare/cache_machines/v0.1.3...cache_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([03e3752](https://github.com/seuros/cache_machines/commit/03e375232563df5cf56b4bbe8435540048b3f2c7))
+
+## [0.1.3](https://github.com/seuros/cache_machines/compare/cache_machines/v0.1.2...cache_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([28635a4](https://github.com/seuros/cache_machines/commit/28635a4df2b2313914957f8cf8b068934bb35f7d))
+
+## [0.1.2](https://github.com/seuros/cache_machines/compare/cache_machines/v0.1.1...cache_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* cross builds no longer compile for the host ([33bc4f3](https://github.com/seuros/cache_machines/commit/33bc4f3fd1ba7bc19bda7930b9d998254d70f923))
+
+## [0.1.1](https://github.com/seuros/cache_machines/compare/cache_machines-v0.1.0...cache_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([3569bc6](https://github.com/seuros/cache_machines/commit/3569bc6ccda4ec7c7bc345ab7be84f92e8edcedd))

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,186 @@
+# CacheMachines
+
+> Sixty-four berths, and a hatch that asks what you've done to deserve one. 📦
+
+An admission-controlled LRU for Ruby. It keeps the most recently used keys in order, names the one it would throw out next, and refuses to throw it out for a newcomer that isn't worth more. You store the payloads and count the hits. It decides what stays.
+
+## Quick Start
+
+```bash
+gem 'cache_machines'
+```
+
+```ruby
+bay = CacheMachines::Lru.new
+
+bay.admit(42, candidate_frequency: 1, victim_frequency: 0)  # => [:inserted, nil]
+bay.admit(7,  candidate_frequency: 1, victim_frequency: 0)  # => [:inserted, nil]
+bay.access(42)                                              # => true
+bay.keys                                                    # => [42, 7]
+bay.remove(7)                                               # => true
+```
+
+Keys are Integers. Pair them with your own storage, hand the decisions to the bay, and the bay tells you what to keep.
+
+## A Message to the Resistance
+
+So you built an LRU cache. Hot rows stay, cold rows fall off the back, dashboards go green. Then the nightly export job runs. It reads every row in the table exactly once, and every one of those reads is a cache miss that inserts a key you will never ask for again.
+
+By the time the export finishes, your working set is gone. The 64 keys that got hit ten thousand times each have been shoved out by 64 keys that got hit once. Monday morning is a cold start, and the LRU did exactly what you told it to do.
+
+LRU answers "what was used least recently?" It never asks "does the newcomer deserve the slot?" This gem asks. When the bay is full, a candidate has to show up with a higher frequency than the key it would evict. Ties lose. The export job's keys never make it past the hatch.
+
+## Chapter 1: Stardate 2025.186, the AMS Denning
+
+> **AMS Denning**, NCC-4203, *Denning*-class cache tender.
+> The hold is finite. The universe of possible consignments is not.
+
+The tender has 64 berths and no more. Every consignment that arrives is logged by key, and the manifest is kept in order of last use. When the bay is full and something new arrives, the quartermaster names the berth at the back, asks how often each has been requisitioned, and only swaps if the newcomer wins outright.
+
+Somewhere in the fleet, a supply officer proposes:
+
+```ruby
+def fetch(key)
+  @cache[key] ||= load(key)     # Hash with 64 entries, oldest shifted off
+end
+```
+
+"That," says the quartermaster, "is how one inventory scan empties the bay."
+
+## The Flight Plan
+
+What happens to a key offered to `admit`:
+
+```mermaid
+stateDiagram-v2
+    [*] --> offered
+    offered --> hit: key already aboard, promoted to front
+    offered --> inserted: bay has a free berth
+    offered --> rejected: bay full, candidate frequency <= victim frequency
+    offered --> evicted: bay full, candidate frequency > victim frequency
+    evicted --> [*]: victim key returned
+    hit --> [*]
+    inserted --> [*]
+    rejected --> [*]
+```
+
+And the night of the export job:
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant Bay as Lru (full)
+    participant Store as Your storage
+
+    App->>Bay: victim
+    Bay-->>App: 17 (seen 4000 times)
+    App->>Bay: admit(export row 9001, candidate 1, victim 4000)
+    Bay-->>App: [:rejected, nil]
+    Note over App: don't cache the row, serve it and move on
+
+    App->>Bay: access(17)
+    Bay-->>App: true, promoted
+
+    App->>Bay: victim
+    Bay-->>App: 23 (seen 2 times)
+    App->>Bay: admit(user 555, candidate 9, victim 2)
+    Bay-->>App: [:evicted, 23]
+    App->>Store: delete 23, store 555
+```
+
+## How the Bay Works
+
+### Admit
+
+`admit` takes the key, how often the candidate has been requested, and how often the current victim has. It returns a status and, only when something was displaced, the evicted key.
+
+```ruby
+bay = CacheMachines::Lru.new
+bay.admit(1, candidate_frequency: 5, victim_frequency: 0)  # => [:inserted, nil]
+bay.admit(1, candidate_frequency: 5, victim_frequency: 0)  # => [:hit, nil]
+```
+
+While there's a free berth, frequencies don't matter. The candidate gets in. A key already aboard is a `:hit` and moves to the front.
+
+### When the bay is full
+
+Fill all 64 berths and the frequencies start to count.
+
+```ruby
+bay = CacheMachines::Lru.new
+64.times { |key| bay.admit(key, candidate_frequency: 0, victim_frequency: 0) }
+
+bay.victim                                                     # => 0
+bay.admit(100, candidate_frequency: 9,  victim_frequency: 9)   # => [:rejected, nil]
+bay.admit(100, candidate_frequency: 8,  victim_frequency: 9)   # => [:rejected, nil]
+bay.admit(100, candidate_frequency: 10, victim_frequency: 9)   # => [:evicted, 0]
+```
+
+Equal loses. Lower loses. Only strictly higher gets a berth, and then you are told exactly which key just left so you can drop its payload.
+
+### Access
+
+A hit promotes the key to the front and returns `true`. A miss returns `false` and inserts nothing. Reading is never admitting.
+
+```ruby
+bay = CacheMachines::Lru.new
+bay.admit(1, candidate_frequency: 0, victim_frequency: 0)
+bay.admit(2, candidate_frequency: 0, victim_frequency: 0)
+
+bay.keys        # => [2, 1]
+bay.access(1)   # => true
+bay.keys        # => [1, 2]
+bay.access(9)   # => false
+bay.size        # => 2
+```
+
+### Victim
+
+`victim` is the key at the back of the line, the one `admit` would evict. It is `nil` until the bay is full. Ask for it right before you admit, look up its frequency, and pass that in.
+
+```ruby
+bay = CacheMachines::Lru.new
+bay.victim                                                   # => nil
+64.times { |key| bay.admit(key, candidate_frequency: 0, victim_frequency: 0) }
+bay.victim                                                   # => 0
+bay.access(0)
+bay.victim                                                   # => 1
+```
+
+### Remove and clear
+
+```ruby
+bay = CacheMachines::Lru.new
+bay.admit(1, candidate_frequency: 0, victim_frequency: 0)
+bay.remove(1)   # => true
+bay.remove(1)   # => false
+bay.clear       # => nil
+bay.empty?      # => true
+```
+
+`keys` is a snapshot, most recent first. Mutate the array all you like; the bay doesn't notice.
+
+## The Rules of the Tender
+
+- **Capacity is 64**, exposed as `CacheMachines::Lru::CAPACITY`. The constructor takes no arguments.
+- **Keys and frequencies are Integers** in `0..2**64-1`. Floats, strings, nil, and objects with `to_int` raise `TypeError`. Negative or too large raises `RangeError`. Bad input is rejected before anything changes.
+- **Both frequencies are keyword arguments** and both are required. Missing or extra keywords raise `ArgumentError`.
+- **Frequencies are yours.** The bay never counts hits. It compares the two numbers you give it and nothing else.
+- **Frozen means frozen.** After `freeze`, every mutator raises `FrozenError`, including a miss on `access` and a `remove` of a key that isn't there.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "A bigger cache would have survived the export."
+### Reality: Any finite cache loses to a scan larger than itself.
+
+The export touches more rows than you have berths. Doubling the bay means it takes twice as long to flush, then flushes anyway. The fix is not more room. The fix is a hatch that asks whether the newcomer has earned a berth, and the answer for a row read once is no.
+
+## What's Yours
+
+The bay holds keys and order, nothing else. Payloads live in your store, and when `admit` returns `:evicted` you delete that payload yourself. Frequency counting is yours too, whether that's a counter per key, a sketch, or a column you already have. Treat `victim` then `admit` as one step in your code; the bay won't stop another thread from slipping in between.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: The export job will read every row once. Make sure once is not enough.**

data/ext/cache_machines_native/core/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.2](https://github.com/seuros/cache_machines/compare/cache-machines-v0.2.1...cache-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([03e3752](https://github.com/seuros/cache_machines/commit/03e375232563df5cf56b4bbe8435540048b3f2c7))
+
+## [0.2.1](https://github.com/seuros/cache_machines/compare/cache-machines-v0.2.0...cache-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([28635a4](https://github.com/seuros/cache_machines/commit/28635a4df2b2313914957f8cf8b068934bb35f7d))
+
+## [0.2.0](https://github.com/seuros/cache_machines/compare/cache-machines-v0.1.0...cache-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([3569bc6](https://github.com/seuros/cache_machines/commit/3569bc6ccda4ec7c7bc345ab7be84f92e8edcedd))

data/ext/cache_machines_native/core/LICENSE

@@ -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/ext/cache_machines_native/core/README.md

@@ -0,0 +1,15 @@
+# cache-machines
+
+> **AMS Denning**, NCC-4203, *Denning*-class cache tender.
+
+Engine-room flight manual: choose which supplies deserve a berth in limited storage.
+
+Allocation-free `no_std` fixed-capacity LRU key policy. Hits move a key to the
+front; accepted new keys evict the least-recently-used key. When full, admission
+requires candidate frequency to exceed the victim's frequency (ties retain the
+incumbent). Frequencies are supplied by the caller, potentially using an existing
+probabilistic sketch; this is not a complete TinyLFU/W-TinyLFU implementation.
+
+Values, loading, eviction callbacks, TTLs, byte weights, synchronization, and sketch
+aging are not owned by this policy. Coordinate key-policy mutations with storage
+updates. A zero-capacity cache rejects every insertion.

data/ext/cache_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+load File.expand_path('ffi/extconf.rb', __dir__)

data/lib/cache_machines/version.rb

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

data/lib/cache_machines.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'cache_machines/version'
+
+# A missing extension is an installation error. There is no Ruby policy fallback.
+require 'cache_machines_native/cache_machines_native'

data/sig/cache_machines.rbs

@@ -0,0 +1,17 @@
+module CacheMachines
+  VERSION: String
+
+  class Lru
+    CAPACITY: Integer
+
+    def self.new: () -> Lru
+    def admit: (Integer key, candidate_frequency: Integer, victim_frequency: Integer) -> [Symbol, Integer?]
+    def access: (Integer key) -> bool
+    def remove: (Integer key) -> bool
+    def clear: () -> nil
+    def keys: () -> Array[Integer]
+    def size: () -> Integer
+    def empty?: () -> bool
+    def victim: () -> Integer?
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: cache_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: x86_64-linux-musl
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: A native binding to the allocation-free cache-machines Rust core. Tracks
+  numeric keys and caller-measured admission frequencies; payload storage and frequency
+  measurement remain with the caller.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/cache_machines_native/core/CHANGELOG.md
+- ext/cache_machines_native/core/LICENSE
+- ext/cache_machines_native/core/README.md
+- ext/cache_machines_native/extconf.rb
+- lib/cache_machines.rb
+- lib/cache_machines/version.rb
+- lib/cache_machines_native/cache_machines_native.so
+- sig/cache_machines.rbs
+homepage: https://github.com/seuros/cache_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/cache_machines
+  bug_tracker_uri: https://github.com/seuros/cache_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: cache_machines_native
+  cargo_manifest_path: ext/cache_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: Bounded native LRU and admission policy for Ruby
+test_files: []