batch_machines 0.1.4-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b025f47eeb70434a02fd8e60cb54e40fd85d896ee7aa9b0d339a85431a065ee9
+  data.tar.gz: ab4add0214d8f2e8f2ad2395ea3c23d698e864f1b3c938fc77f2502185bd7e72
+SHA512:
+  metadata.gz: d7ad31e137d1522835281ae35105b9fa7b2e1669e1e1f3fe432b5b7d73f017ee341f051796ea620f6d4f1a61e5317ea5a0dbe030110d3342042fe9b1ab83bbcb
+  data.tar.gz: 2c80d8c18535ae0ea8e40b9b797e5fd905733164df4f180fab201057e58f7fb25d4033713d67e80225c48059f8855f5be2326ff2e522dcfce62d94786d072c20

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.1.4](https://github.com/seuros/batch_machines/compare/batch_machines/v0.1.3...batch_machines/v0.1.4) (2026-11-06)
+
+
+### Features
+
+* expose the pending deadline and weighted pushes ([9044fa3](https://github.com/seuros/batch_machines/commit/9044fa323859bcd6fb6cf9a7b5c884bf503fedc4))
+
+## [0.1.3](https://github.com/seuros/batch_machines/compare/batch_machines/v0.1.2...batch_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([b150571](https://github.com/seuros/batch_machines/commit/b150571563871f7af013b716402aa169688deaf2))
+
+## [0.1.2](https://github.com/seuros/batch_machines/compare/batch_machines/v0.1.1...batch_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([2287c10](https://github.com/seuros/batch_machines/commit/2287c1089fefd9154740078a6977598f47033d0e))
+
+## [0.1.1](https://github.com/seuros/batch_machines/compare/batch_machines-v0.1.0...batch_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([da62e4b](https://github.com/seuros/batch_machines/commit/da62e4bb16f3d1eaecc93ebf2a739f86fcfee932))

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,219 @@
+# BatchMachines
+
+> Fewer launches, fuller holds, and nobody left sitting on the pad. 🚚
+
+A batching policy for Ruby. You tell it how big a batch may get and how long the oldest item may wait. Every time something arrives you `push` the clock, and it tells you whether to keep buffering or send now. On your timer you `poll`, and it tells you if the oldest item has waited long enough. When you've sent, you `flush`. It never sees your payloads. It only ever answers one question: is now the time?
+
+## Quick Start
+
+```bash
+gem 'batch_machines'
+```
+
+```ruby
+# Up to 500 rows per insert, and no row waits longer than 50ms.
+batch = BatchMachines::Batch.new(500, 50_000_000)
+rows = []
+
+def ingest(batch, rows, row)
+  rows << row
+  case batch.push(now_ns)
+  when 'size', 'deadline' then insert_all(batch, rows)
+  end
+end
+
+def tick(batch, rows)
+  insert_all(batch, rows) if batch.poll(now_ns)
+end
+
+def insert_all(batch, rows)
+  Row.insert_all(rows)
+  rows.clear
+  batch.flush(now_ns)
+end
+```
+
+Time is Integer nanoseconds from a monotonic clock. `now_ns` is whatever you use for that, such as `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`.
+
+## A Message to the Resistance
+
+So the event stream got busy and you were doing one INSERT per event. The database said no. You switched to batches of 500, and throughput went up tenfold. Then support opened a ticket: the last 37 events of every day show up the next morning, because 37 is less than 500 and nothing ever told them to go.
+
+You added a timer. Now there's a batch size *and* a deadline, and a ticket about which one wins when both fire in the same tick, and another about the deadline resetting every time an item arrives so a steady trickle never flushes at all.
+
+This is Nagle's problem from 1984 with the names changed. Group small things into bigger things, but never make the first small thing wait forever. The bookkeeping for that is three numbers: how many are waiting, how many you want before sending, and when the oldest one arrived. This gem keeps those three numbers and makes the call. The sending is still yours.
+
+## Chapter 1: Stardate 2025.186, the AMS Nagle
+
+> **AMS Nagle**, NCC-4202, *Nagle*-class cargo consolidator.
+> Fewer launches. Fuller holds. No forgotten departure deadline.
+
+The consolidator doesn't fly. It watches the loading bay. Every pod that rolls in is logged, and the moment the hold reaches target size, or the first pod has sat on the deck for its full wait, the launch order goes out. One launch per pod burns the convoy's fuel. One pod waiting a week burns the mission.
+
+Somewhere in the bay, a loading officer proposes:
+
+```ruby
+def enqueue(row)
+  buffer << row
+  flush_all if buffer.size >= 500
+end
+```
+
+"That," says the consolidator, "is how thirty-seven pods spend the night on the deck."
+
+## The Flight Plan
+
+Three things can be true of the hold: it has room and no reason to launch, it has reached its target, or the first pod has waited too long. Deadline beats size when both are true.
+
+```mermaid
+stateDiagram-v2
+    [*] --> empty
+    empty --> buffering: push, buffered (oldest timestamp set)
+    buffering --> buffering: push, buffered
+    buffering --> size_ready: push or poll, pending >= target
+    buffering --> deadline_ready: push or poll, oldest waited max_wait
+    size_ready --> deadline_ready: oldest waited max_wait
+    size_ready --> size_ready: push accepted (until capacity, then full)
+    size_ready --> empty: flush
+    deadline_ready --> empty: flush
+    buffering --> empty: flush
+```
+
+And a slow evening, with a trickle that never reaches 500:
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant Batch
+    participant DB
+
+    App->>Batch: push(t=0ms)
+    Batch-->>App: buffered
+    App->>Batch: push(t=20ms)
+    Batch-->>App: buffered
+    App->>Batch: push(t=45ms)
+    Batch-->>App: buffered
+    Note over Batch: oldest arrived at 0ms, max wait 50ms
+
+    App->>Batch: poll(t=50ms)
+    Batch-->>App: deadline
+    App->>DB: INSERT 3 rows
+    App->>Batch: flush(t=51ms)
+    Batch-->>App: 3
+    Note over Batch: hold empty, no deadline pending
+```
+
+## How the Hold Works
+
+### Push
+
+Every arrival is a `push` with the current time. The return value is a String telling you what to do.
+
+```ruby
+batch = BatchMachines::Batch.new(2, 10)
+
+batch.push(1)    # => "buffered"   room left, no reason to send
+batch.push(2)    # => "size"       target reached, send now
+batch.push(3)    # => "full"       capacity reached, this one was NOT accepted
+batch.pending    # => 2
+```
+
+`"buffered"`, `"size"`, and `"deadline"` all mean the item was counted. `"full"` means it wasn't, and you need to flush before it can be. Keep your own list of payloads alongside, and only append when the push was accepted.
+
+### Poll
+
+Nothing arrives, time passes. `poll` asks the same question without adding anything. It answers `nil` when there's nothing to do.
+
+```ruby
+batch = BatchMachines::Batch.new(100, 50_000_000)
+batch.push(1_000)
+batch.push(40_000_000)
+
+batch.poll(50_000_999)   # => nil         oldest has waited 49.999999ms
+batch.poll(50_001_000)   # => "deadline"  oldest has waited 50ms
+```
+
+The deadline belongs to the oldest item and never moves. A new arrival doesn't push it back, and neither does changing the target.
+
+### Flush
+
+When you've sent, say so. `flush` returns how many were waiting and empties the hold.
+
+```ruby
+batch.flush(50_001_000)   # => 2
+batch.flush(50_001_000)   # => 0
+batch.poll(60_000_000)    # => nil
+```
+
+Flushing an empty hold is fine and returns zero.
+
+### Deadline wins
+
+When an arrival both fills the target and lands at the deadline, you hear about the deadline. The older reason takes precedence.
+
+```ruby
+batch = BatchMachines::Batch.new(2, 10)
+batch.push(0)     # => "buffered"
+batch.push(10)    # => "deadline"
+```
+
+### Adapting the target
+
+The target size starts at capacity. If you'd rather it follow conditions downstream, such as insert latency, feed `adapt` an error signal and it moves the target for you, clamped to `1..capacity`. Out of the box it's a proportional controller with gain 1, so the target simply follows the number you give it. The second argument is how much time passed since the last call, in nanoseconds.
+
+```ruby
+batch = BatchMachines::Batch.new(100, 50_000_000)
+batch.target                         # => 100
+
+batch.adapt(10, 1_000_000_000)       # => 10
+batch.adapt(-3, 1_000_000_000)       # => 1     never below one
+batch.adapt(1000, 1_000_000_000)     # => 100   never above capacity
+```
+
+Need memory? `configure_pid(p, i, d)` sets the gains. With only an integral gain the target climbs a little more each call:
+
+```ruby
+batch = BatchMachines::Batch.new(100, 10)
+batch.configure_pid(0, 1.0, 0)
+
+batch.adapt(5.0, 1_000_000_000)   # => 5
+batch.adapt(5.0, 1_000_000_000)   # => 10
+batch.adapt(5.0, 1_000_000_000)   # => 15
+```
+
+Lowering the target doesn't drop anything already in the hold. Items past the target still count, and the next push or poll says `"size"` until you flush.
+
+```ruby
+batch = BatchMachines::Batch.new(5, 10)
+batch.push(0)
+batch.adapt(2.0, 1_000_000_000)   # => 2
+batch.push(1)                     # => "size"
+batch.push(2)                     # => "size"   accepted, still under capacity 5
+batch.pending                     # => 3
+```
+
+## The Rules of the Consolidator
+
+- **Capacity is an Integer** in `1...2**32`, and `max_wait_ns` is a positive Integer. Zero for either raises `ArgumentError`.
+- **Time is unsigned 64-bit Integer nanoseconds.** Floats and strings raise `TypeError`, negative or overflow raises `RangeError`.
+- **Time only moves forward.** A `push` with an earlier clock than the last one returns `"rejected"` and counts nothing. `poll` and `flush` with an earlier clock return `nil` and change nothing.
+- **Gains are finite and non-negative.** Infinite, NaN, or negative gains raise `ArgumentError`. An error of infinity or NaN raises too, and `adapt` with zero elapsed raises.
+- **A blown-up controller returns `nil`** and leaves the target where it was, rather than handing you a nonsense size.
+- **Frozen means frozen.** `freeze` the batch and `push`, `poll`, `flush`, `adapt`, and `configure_pid` all raise `FrozenError`.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "Batch of 500 or 50ms, whichever comes first. Easy."
+### Reality: Whichever comes first, measured from when?
+
+Measured from the newest item and a steady trickle never flushes. Measured from the last flush and the first item after a quiet hour waits the full 50ms plus however long the hour was. Measured from the oldest item, with the deadline pinned the moment it lands, and everything behaves. That last one is the only correct answer and it's the only one this gem knows how to give.
+
+## What's Yours
+
+The batch counts. It doesn't hold your rows, doesn't run a timer, and doesn't call the database. You keep the payloads in a list next to it, you call `poll` from whatever tick you already have, and you call `flush` after the send actually succeeded, not before. If the send fails, don't flush. The hold still knows how many are waiting and when the oldest arrived.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: The last thirty-seven events of the day are still events. Someone has to tell them to go.**

data/ext/batch_machines_native/core/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.3.0](https://github.com/seuros/batch_machines/compare/batch-machines-v0.2.2...batch-machines-v0.3.0) (2026-11-06)
+
+
+### Features
+
+* expose the pending deadline and weighted pushes ([9044fa3](https://github.com/seuros/batch_machines/commit/9044fa323859bcd6fb6cf9a7b5c884bf503fedc4))
+
+## [0.2.2](https://github.com/seuros/batch_machines/compare/batch-machines-v0.2.1...batch-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([b150571](https://github.com/seuros/batch_machines/commit/b150571563871f7af013b716402aa169688deaf2))
+
+## [0.2.1](https://github.com/seuros/batch_machines/compare/batch-machines-v0.2.0...batch-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([2287c10](https://github.com/seuros/batch_machines/commit/2287c1089fefd9154740078a6977598f47033d0e))
+
+## [0.2.0](https://github.com/seuros/batch_machines/compare/batch-machines-v0.1.0...batch-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([da62e4b](https://github.com/seuros/batch_machines/commit/da62e4bb16f3d1eaecc93ebf2a739f86fcfee932))

data/ext/batch_machines_native/core/README.md

@@ -0,0 +1,21 @@
+# batch-machines
+
+> **AMS Nagle**, NCC-4202, *Nagle*-class cargo consolidator.
+
+Engine-room flight manual: fill the cargo hold without missing the launch window.
+
+Allocation-free `no_std` size/deadline batch decisions. The first item establishes
+a fixed maximum-wait deadline; later arrivals and target adaptation never move
+that deadline. Poll with explicit monotonic time, or read `deadline()` and sleep
+until it: it is the absolute time at which `poll` first reports `Deadline`, and
+`None` while nothing is pending. A flush recommendation does not flush payloads:
+the adapter must execute/acknowledge the flush, which also clears the deadline.
+
+Capacity is a budget of cost units. `push` spends one unit per item;
+`push_weighted` spends the item's cost, so a byte budget flushes at a byte
+target. An item costing more than the capacity is never admitted. Flow credits
+bound the pending cost. PID output can adapt the target cost, truncated toward
+zero and clamped to `[1, capacity]`. Error definition, gains,
+measurement, and downstream flush concurrency are caller policies. This cannot
+guarantee an end-to-end latency budget if timers/execution are delayed. No I/O,
+timer driver, payload storage, partial flush, or Ruby binding is included.

data/ext/batch_machines_native/extconf.rb

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

data/lib/batch_machines/version.rb

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

data/lib/batch_machines.rb

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

data/sig/batch_machines.rbs

@@ -0,0 +1,13 @@
+module BatchMachines
+  VERSION: String
+  class Batch
+    def self.new: (Integer capacity, Integer max_wait_ns) -> instance
+    def configure_pid: (Float | Integer p, Float | Integer i, Float | Integer d) -> nil
+    def push: (Integer now_ns) -> String
+    def poll: (Integer now_ns) -> String?
+    def flush: (Integer now_ns) -> Integer?
+    def adapt: (Float | Integer error, Integer elapsed_ns) -> Integer?
+    def pending: () -> Integer
+    def target: () -> Integer
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: batch_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: arm64-darwin
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: Initial native batch policy model. Caller owns payloads and execution.
+  Local sibling Rust checkouts required.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/batch_machines_native/core/CHANGELOG.md
+- ext/batch_machines_native/core/README.md
+- ext/batch_machines_native/extconf.rb
+- lib/batch_machines.rb
+- lib/batch_machines/version.rb
+- lib/batch_machines_native/batch_machines_native.bundle
+- sig/batch_machines.rbs
+homepage: https://github.com/seuros/batch_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/batch_machines
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: batch_machines_native
+  cargo_manifest_path: ext/batch_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 size/deadline batch decisions with PID adaptation
+test_files: []