raptor 0.16.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e564259e8919bb36ded41097d9f3930fcf6ad2f2d090cd4bf0a2ef4cbf424b4
-  data.tar.gz: 1bf2f2e1077af1c2b61ba4b52bd5b13460bf0f27105a355b5dc01ff05e62b7b8
+  metadata.gz: df28f67647ac4c928757722392b5a0da9f61a31c6f81ad7126b6023b12311355
+  data.tar.gz: 5f7e1298a2aa0fb6622db15749b503261b62a4321549b39f955282285bd74c0c
 SHA512:
-  metadata.gz: 103f96d2f2490ea4bd1f844f29a8980deba5881e52b3c684ec2db963c0b0b0d426d616ce66ff22be93736550583891862502c1216663426249e015e1c68ab29d
-  data.tar.gz: e377a59417305334b255cf08be1c8c257971840d244b8b14b461ebbdfb857dc5a8cfbd6d37bee26ab2dc95642601bd1b7640100277c0b401f225fab66bbf8c77
+  metadata.gz: 00bc3616aa1877c4b79f3acdf00165981ed6401e3a2fb16a2c1565ef92b557772dd1960b31f85b370778e3f2f735904eca6b8cf969ca4aa1f62de3687aea1839
+  data.tar.gz: af947a551e8f0e3b8d07bd8c07e9b1e686e8f36a1d48af458fb331e1ca8c937f44504b4c9895c233cfe3905d22bce1176d57438baa428e9d44257edc46ba5c1f

data/.buildkite/pipeline.yml

@@ -41,7 +41,7 @@ steps:
         soft_fail: true
         image: "rubylang/ruby:master-dev"
         commands:
-          - apt-get update && apt-get install -y libyaml-dev
+          - apt-get update && apt-get install -y libyaml-dev libssl-dev
           - ruby -v
           - bundle install
           - bundle exec rake ci
@@ -52,7 +52,7 @@ steps:
         env:
           RUBY_YJIT_ENABLE: "1"
         commands:
-          - apt-get update && apt-get install -y libyaml-dev
+          - apt-get update && apt-get install -y libyaml-dev libssl-dev
           - ruby -v
           - bundle install
           - bundle exec rake ci
@@ -63,7 +63,7 @@ steps:
         env:
           RUBY_GC_STRESS: "1"
         commands:
-          - apt-get update && apt-get install -y libyaml-dev
+          - apt-get update && apt-get install -y libyaml-dev libssl-dev
           - ruby -v
           - bundle install
           - bundle exec rake ci
@@ -75,7 +75,7 @@ steps:
           RUBY_YJIT_ENABLE: "1"
           RUBY_GC_STRESS: "1"
         commands:
-          - apt-get update && apt-get install -y libyaml-dev
+          - apt-get update && apt-get install -y libyaml-dev libssl-dev
           - ruby -v
           - bundle install
           - bundle exec rake ci

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.18.0] - 2026-08-29
+
+- Add adaptive application thread scaling with `max_threads`
+
+## [0.17.0] - 2026-08-29
+
+- Reserve BPF-routed connections before accept
+- Skip unnecessary HTTP/1.1 response work
+- Assemble HTTP/2 response headers in C
+- Emit HTTP/1.1 response headers and chunked bodies in C
+- Decode chunked request bodies in C
+
 ## [0.16.1] - 2026-08-23
 
 - Drop the stale `Ractors=NUM` option from the Rackup handler

data/README.md

@@ -37,7 +37,7 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 ```
 > bundle exec raptor -w 10 -t 3 hello_world.ru
 [Raptor 83654|Main|Main] Cluster initializing:
-[Raptor 83654|Main|Main] ├─ Version: 0.16.1
+[Raptor 83654|Main|Main] ├─ Version: 0.18.0
 [Raptor 83654|Main|Main] ├─ Ruby Version: ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
 [Raptor 83654|Main|Main] ├─ Environment: development
 [Raptor 83654|Main|Main] ├─ Master PID: 83654
@@ -93,6 +93,7 @@ The config file is a Ruby file that evaluates to a hash of options. By default R
   drain_accept_queue: false,
   workers: 4, # `Etc.nprocessors`
   threads: 3,
+  max_threads: nil, # `Float::INFINITY` for no limit
   chdir: nil,
   environment: nil, # falls back to `RAILS_ENV`, then `RACK_ENV`, then `"development"`
   connection: {
@@ -128,6 +129,11 @@ The config file is a Ruby file that evaluates to a hash of options. By default R
 }
 ```
 
+`threads` sets the number of application threads each worker keeps running. Set `max_threads` above it to let Raptor
+add temporary threads when queued work is held up by blocking operations, or use `Float::INFINITY` for no limit.
+Raptor does not add threads when waiting for the GVL is the bottleneck. Temporary threads leave after the queue
+drains. The default `nil` keeps the pool fixed at `threads`.
+
 ## Bindings
 
 Raptor accepts multiple `binds:` URIs across three schemes.
@@ -188,8 +194,8 @@ KillMode=mixed
 
 ## Stats
 
-Each worker writes per-worker stats (request count, busy threads, backlog, last check-in) to shared memory and to a
-JSON file (default `tmp/raptor.json`; set via `stats_file`).
+Each worker writes per-worker stats (request count, busy and available threads, backlog, last check-in) to shared
+memory and to a JSON file (default `tmp/raptor.json`; set via `stats_file`).
 
 ```
 > bundle exec raptor stats
@@ -201,29 +207,40 @@ Worker 1 (phase 0): pid=91351, requests=1199, busy=1/3, backlog=0, booted, last_
 
 ## (Micro) Benchmarks
 
-Raptor 0.16.1 vs Puma 8.0.2 vs Falcon 0.57.0 across two workload profiles. **IO-bound** is a GET endpoint that
+Raptor 0.18.0 vs Puma 8.0.2 vs Falcon 0.57.0 across two workload profiles. **IO-bound** is a GET endpoint that
 interleaves 5-10 short sleeps (total 2.5-15ms) with small CPU work, simulating a read path that makes several DB or
 cache calls. **CPU-bound** is a POST endpoint that accepts a small JSON body, interleaves 3-5 chunks of JSON item
 building (total 450-1500 items) with sub-100µs sleeps, and returns the built array, simulating a write path that does
 most of its work in Ruby with a few near-zero-cost cache hits.
 
-Each cell reports the median throughput and median p95 latency independently across 5 runs, so the two numbers in a row
+Raptor is run in two modes: **Fixed** keeps 3 application threads per worker, matching Puma, while **Scaling** starts
+with 3 and may add threads without a fixed limit when queued work is blocked outside the GVL. Both modes are compared
+with both Puma and Falcon in the table below.
+
+Each cell reports the median throughput and median p95 latency independently across 3 runs, so the two numbers in a row
 may come from different runs. Every run starts a fresh server process so the samples are independent of each other;
 state accumulated in a previous run cannot bias the next. Across the whole table, the widest spread
-((max - min) / 2 / median) between runs of a single cell was ±24.8% for throughput and ±40.3% for p95.
-
-| Protocol              | Workload | Raptor req/s | Raptor p95 | Puma req/s  | Puma p95  | vs Puma req/s | vs Puma p95  | Falcon req/s | Falcon p95 | vs Falcon req/s | vs Falcon p95 |
-| --------------------- | -------- | ------------ | ---------- | ----------- | --------- | ------------- | ------------ | ------------ | ---------- | --------------- | ------------- |
-| HTTP/1.1              | IO       | 3.21k req/s  | 63.20 ms   | 1.48k req/s | 131.00 ms | 117.7% higher | 51.8% lower  | 12.27k req/s | 14.00 ms   | 73.8% lower     | 351.4% higher |
-| HTTP/1.1              | CPU      | 8.29k req/s  | 33.30 ms   | 8.56k req/s | 21.20 ms  | 3.2% lower    | 57.1% higher | 6.62k req/s  | 27.00 ms   | 25.2% higher    | 23.3% higher  |
-| HTTP/1.1 (keep-alive) | IO       | 2.43k req/s  | 54.40 ms   | 1.44k req/s | 110.20 ms | 68.7% higher  | 50.6% lower  | 6.28k req/s  | 27.90 ms   | 61.3% lower     | 95.0% higher  |
-| HTTP/1.1 (keep-alive) | CPU      | 8.40k req/s  | 18.80 ms   | 8.49k req/s | 21.90 ms  | 1.1% lower    | 14.2% lower  | 7.09k req/s  | 31.50 ms   | 18.5% higher    | 40.3% lower   |
-| HTTP/2                | IO       | 0.97k req/s  | 197.97 ms  | N/A         | N/A       | -             | -            | 6.59k req/s  | 27.21 ms   | 85.2% lower     | 627.6% higher |
-| HTTP/2                | CPU      | 6.61k req/s  | 31.98 ms   | N/A         | N/A       | -             | -            | 8.09k req/s  | 45.04 ms   | 18.3% lower     | 29.0% lower   |
+((max - min) / 2 / median) between runs of a single cell was ±26.6% for throughput and ±45.2% for p95.
+
+| Protocol              | Workload | Raptor mode | Raptor req/s | Raptor p95 | Puma req/s  | Puma p95  | vs Puma req/s | vs Puma p95  | Falcon req/s | Falcon p95 | vs Falcon req/s | vs Falcon p95 |
+| --------------------- | -------- | ----------- | ------------ | ---------- | ----------- | --------- | ------------- | ------------ | ------------ | ---------- | --------------- | ------------- |
+| HTTP/1.1              | IO       | Fixed       | 3.11k req/s  | 60.50 ms   | 1.51k req/s | 123.80 ms | 106.1% higher | 51.1% lower  | 12.20k req/s | 14.20 ms   | 74.5% lower     | 326.1% higher |
+| HTTP/1.1              | IO       | Scaling     | 8.63k req/s  | 21.60 ms   | 1.51k req/s | 123.80 ms | 471.4% higher | 82.6% lower  | 12.20k req/s | 14.20 ms   | 29.3% lower     | 52.1% higher  |
+| HTTP/1.1              | CPU      | Fixed       | 8.22k req/s  | 25.40 ms   | 8.65k req/s | 20.90 ms  | 5.0% lower    | 21.5% higher | 6.52k req/s  | 27.40 ms   | 26.0% higher    | 7.3% lower    |
+| HTTP/1.1              | CPU      | Scaling     | 8.22k req/s  | 25.10 ms   | 8.65k req/s | 20.90 ms  | 4.9% lower    | 20.1% higher | 6.52k req/s  | 27.40 ms   | 26.1% higher    | 8.4% lower    |
+| HTTP/1.1 (keep-alive) | IO       | Fixed       | 3.21k req/s  | 45.90 ms   | 1.46k req/s | 105.50 ms | 119.5% higher | 56.5% lower  | 6.23k req/s  | 28.20 ms   | 48.6% lower     | 62.8% higher  |
+| HTTP/1.1 (keep-alive) | IO       | Scaling     | 9.43k req/s  | 21.60 ms   | 1.46k req/s | 105.50 ms | 545.8% higher | 79.5% lower  | 6.23k req/s  | 28.20 ms   | 51.3% higher    | 23.4% lower   |
+| HTTP/1.1 (keep-alive) | CPU      | Fixed       | 8.49k req/s  | 21.80 ms   | 8.54k req/s | 22.20 ms  | 0.7% lower    | 1.8% lower   | 6.86k req/s  | 32.70 ms   | 23.8% higher    | 33.3% lower   |
+| HTTP/1.1 (keep-alive) | CPU      | Scaling     | 8.49k req/s  | 22.20 ms   | 8.54k req/s | 22.20 ms  | 0.6% lower    | 0.0% higher  | 6.86k req/s  | 32.70 ms   | 23.8% higher    | 32.1% lower   |
+| HTTP/2                | IO       | Fixed       | 1.14k req/s  | 150.03 ms  | N/A         | N/A       | -             | -            | 6.40k req/s  | 28.07 ms   | 82.1% lower     | 434.4% higher |
+| HTTP/2                | IO       | Scaling     | 4.46k req/s  | 39.65 ms   | N/A         | N/A       | -             | -            | 6.40k req/s  | 28.07 ms   | 30.3% lower     | 41.2% higher  |
+| HTTP/2                | CPU      | Fixed       | 5.35k req/s  | 35.99 ms   | N/A         | N/A       | -             | -            | 7.32k req/s  | 41.05 ms   | 26.9% lower     | 12.3% lower   |
+| HTTP/2                | CPU      | Scaling     | 6.28k req/s  | 32.32 ms   | N/A         | N/A       | -             | -            | 7.32k req/s  | 41.05 ms   | 14.2% lower     | 21.3% lower   |
 
 > ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [aarch64-linux]
-> 10 worker processes; Raptor and Puma run 3 threads per worker, Falcon runs unbounded fibers per worker;
-> 120 concurrent HTTP/1.1 client connections; 40 concurrent HTTP/2 client connections × 3 streams each
+> 10 worker processes; fixed Raptor and Puma run 3 threads per worker; scaling Raptor starts at 3 with no fixed limit;
+> Falcon runs unbounded fibers per worker; 120 concurrent HTTP/1.1 client connections; 40 concurrent HTTP/2 client
+> connections × 3 streams each
 
 See [bin/benchmark](bin/benchmark) for more details.
 

data/docs/brisrails-talk.md

@@ -37,7 +37,7 @@ _[luma.com/t3l24s8h](https://luma.com/t3l24s8h)_
 - <big>I built a Ruby web server over the last few months</big>
 - <big>It's called Raptor</big>
 - <big>It runs Rack apps, like Puma and Falcon do</big>
-- <big>It's built around Ruby 4's Ractors</big>
+- <big>It's built around a Ractor-parallel HTTP parser</big>
 - <big>It's fast enough that the numbers are interesting</big>
 - <big>It's not production-ready. Nobody's Rails app should be behind it yet.</big>
 
@@ -72,7 +72,7 @@ _[luma.com/t3l24s8h](https://luma.com/t3l24s8h)_
   - Red-black trees
   - Anonymous shared memory via mmap
   - eBPF programs running inside the Linux kernel
-- <big>All in Ruby. All working together in one gem.</big>
+- <big>Ruby APIs, native extensions, and one tiny BPF program, all working together in one server.</big>
 
 <br>
 <br>
@@ -239,7 +239,7 @@ One thing to note: the whole `SYN` → `SYN-ACK` → `ACK` handshake at the top
 
 - <big>Kernel does the handshake and puts the completed connection on the listener's accept queue</big>
 - <big>Server calls `accept_nonblock` to pull the next connection off the queue</big>
-- <big>The BPF program we'll see later runs during the SYN phase, deciding which listener's queue the connection gets placed in</big>
+- <big>For Raptor's plain-TCP listener, the BPF program we'll see later can choose which worker socket receives each new connection</big>
 
 <br>
 <br>
@@ -273,8 +273,8 @@ One thing to note: the whole `SYN` → `SYN-ACK` → `ACK` handshake at the top
 
 **[Falcon](https://github.com/socketry/falcon)**
 
-- <big>One fiber per request instead of threads</big>
-  - A fiber is a lightweight coroutine, about 5KB versus a thread's ~1MB
+- <big>Lightweight async tasks backed by fibers instead of a fixed app thread pool</big>
+  - Fibers are cooperatively scheduled coroutines and much cheaper to create than OS threads
 - <big>Built on the [`async`](https://github.com/socketry/async) gem, mostly written by Samuel Williams ([`@ioquatix`](https://github.com/ioquatix))</big>
 - <big>Speaks HTTP/2 natively</big>
 - <big>Excellent at long-lived connections and streaming</big>
@@ -535,9 +535,9 @@ If parsing runs in a Ractor:
 
 - <big>It uses a **different GVL** than the app</big>
 - <big>On a two-core machine, the parser and the app can run at the exact same instant</big>
-- <big>Actual parallelism inside one request pipeline</big>
+- <big>Actual protocol and app parallelism inside one worker process</big>
 
-That's the whole idea. Everything else in Raptor grew out of taking it seriously.
+That's the whole idea. Raptor uses that pipeline when a connection needs the reactor; complete requests on its eager paths parse inline instead of paying for a Ractor handoff.
 
 <br>
 <br>
@@ -591,6 +591,7 @@ flowchart TB
 
         STA["Stats thread<br/>writes 1 Hz"]
 
+        SRV -->|"complete first read"| ATP
         SRV --> RCT
         RCT --> RP1
         RCT --> RP2
@@ -759,7 +760,7 @@ flowchart LR
 
 - <big>App threads share one GVL among themselves. Only one runs Ruby at a time.</big>
 - <big>The pipeline Ractor has its own GVL. It runs Ruby independently.</big>
-- <big>Two Ruby threads can run Ruby code at the same time, on two CPU cores, on the same request pipeline</big>
+- <big>A pipeline Ractor and an app thread can run Ruby code at the same time, on two CPU cores</big>
 - <big>That is not something you get out of the box in Ruby</big>
 
 <br>
@@ -786,7 +787,7 @@ flowchart LR
 
 Where your Rack app runs, and where the response gets written back to the socket.
 
-- <big>Puma's pool is a `Mutex + ConditionVariable + Array`</big>
+- <big>Puma's pool coordinates a Ruby `Queue` with `Mutex + ConditionVariable`</big>
 - <big>Every enqueue and every dequeue takes the mutex</big>
 - <big>Under low concurrency, it's fine</big>
 - <big>Under contention, the mutex becomes a serialisation point</big>
@@ -794,7 +795,7 @@ Where your Rack app runs, and where the response gets written back to the socket
 
 Raptor's pool is **lock-free on the hot path**.
 
-To explain that, one minute on one CPU instruction.
+To explain that, one minute on one atomic primitive.
 
 <br>
 <br>
@@ -831,13 +832,13 @@ flowchart LR
     T2 -->|"CAS(42, 77)<br/>fails because current is now 99"| Memory
 ```
 
-- <big>A single CPU instruction</big>
+- <big>A hardware-supported atomic operation</big>
 - <big>Reads a memory word</big>
 - <big>Compares to what you expected</big>
 - <big>If they match, replaces with a new value</big>
 - <big>All atomically. No lock.</big>
 
-On x86 it's `LOCK CMPXCHG`. On ARM it's `LDXR` / `STXR`.
+On x86 it is commonly `LOCK CMPXCHG`. On ARM it is commonly an exclusive load/store pair such as `LDXR` / `STXR`.
 
 <br>
 <br>
@@ -867,15 +868,15 @@ On x86 it's `LOCK CMPXCHG`. On ARM it's `LDXR` / `STXR`.
 cas(@slot, expected, new_value)
 ```
 
-- <big>If you can build a data structure so "publish a new version" is one CAS, you never need a lock</big>
+- <big>If a state transition can be published with CAS, threads do not need a lock for that transition</big>
 - <big>If the CAS fails, you retry (someone else got there first)</big>
-- <big>Every high-performance concurrent data structure you've heard of is built on this</big>
+- <big>Many high-performance concurrent data structures are built on this</big>
   - Java's `ConcurrentHashMap`
   - Rust's `AtomicUsize`
   - Go's `sync/atomic`
 - <big>[`concurrent-ruby`](https://github.com/ruby-concurrency/concurrent-ruby) has had CAS primitives (`AtomicReference`, `AtomicBoolean`, `AtomicFixnum`) since 2013</big>
-  - But its primitives aren't Ractor-safe, they touch class-level state Ractors can't reach
-  - Ractor-safe CAS in Ruby is what Raptor needed, and it's what `atomic-ruby` gives you
+  - I could have built around those primitives, but Raptor also needed a lock-free FIFO and lock-free waiter parking
+  - I built that smaller, native set of pieces as `atomic-ruby`, with its C extension explicitly marked Ractor-safe
 
 <br>
 <br>
@@ -950,10 +951,10 @@ Where it pays off:
 
 Why we picked CAS for Raptor's thread pool:
 
-- <big>Enqueue and dequeue are each one publish operation, exactly what CAS is for</big>
+- <big>The queue can publish head, tail, and link changes through small atomic steps</big>
 - <big>The server thread reads pool metrics on every accept iteration, thousands of times per second</big>
-- <big>Under a mutex, every read of the queue length blocks writers, and every write blocks readers</big>
-- <big>Under CAS, reads are just atomic loads. Free. Never contend with writes.</big>
+- <big>Under a queue-wide mutex, readers and writers serialise around the same lock</big>
+- <big>Atomic counters avoid that lock. They still cost a synchronised memory access, but they do not park another thread.</big>
 
 <br>
 <br>
@@ -980,11 +981,12 @@ Why we picked CAS for Raptor's thread pool:
 Another gem I wrote. Native C extension. Exposes CAS-based primitives to Ruby:
 
 - <big>`Atom` – a CAS-protected reference cell holding one Ruby value</big>
-- <big>`AtomicBoolean`, `AtomicInteger` – type-specialised versions</big>
+- <big>`AtomicBoolean` – a type-specialised boolean</big>
+- <big>`AtomicQueue` – a multi-producer, multi-consumer FIFO</big>
 - <big>`AtomicThreadPool` – the thread pool Raptor uses</big>
 - <big>`AtomicConditionVariable` – lock-free waiter parking</big>
 
-Ruby's `VALUE` type on 64-bit is a tagged pointer. Fits in one CPU word. So `atom.swap` compiles down to one instruction.
+Ruby's `VALUE` type on 64-bit is a tagged pointer. It fits in one machine word, so the native extension can compare and replace the reference atomically.
 
 ```c
 old = ATOMIC_VALUE_CAS(&atom->value, expected, new_value);
@@ -1010,27 +1012,19 @@ old = ATOMIC_VALUE_CAS(&atom->value, expected, new_value);
 <br>
 <br>
 
-## The Banker's queue
+## The Michael-Scott queue
 
-Raptor's thread pool stores its queue as a frozen `Hash` inside an `Atom`:
-
-```ruby
-{ in: [...], out: [...], count:, shutdown: }
-```
+Raptor's thread pool uses a lock-free linked FIFO from `atomic-ruby`:
 
 ```mermaid
 flowchart LR
-    subgraph Q["Atom value"]
-        In["in: [C, B, A]<br/>latest first"]
-        Out["out: []"]
-    end
-
-    Push["enqueue D"] -->|"one CAS to<br/>{in: [D,C,B,A], out: []}"| Q2["…"]
-
-    subgraph Q3["When out is empty, flip"]
-        In3["in: []"]
-        Out3["out: [A, B, C, D]"]
-    end
+    H["atomic head"] --> S["dummy sentinel"]
+    S --> A["work A"]
+    A --> B["work B"]
+    B --> N["nil"]
+    T["atomic tail"] --> B
+    P["producer: work C"] -->|"CAS B.next from nil to C<br/>then advance tail"| C["work C"]
+    Q["consumer"] -->|"read A<br/>CAS head from S to A"| H
 ```
 
 <br>
@@ -1055,19 +1049,54 @@ flowchart LR
 
 ## Why this pattern works
 
-- <big>Two stacks. Push to `in`. Pop from `out`.</big>
-- <big>When `out` is empty, atomically flip `in` (reversed) into `out`</big>
-- <big>Amortised O(1) per operation</big>
-- <big>One CAS per operation</big>
+- <big>A dummy node separates the queue's head position from its first value</big>
+- <big>Producers append at the tail; consumers advance the head</big>
+- <big>Multiple producers and consumers can make progress without one queue-wide lock</big>
+- <big>Push and pop are O(1), with CAS retries when another thread wins a race</big>
 - <big>Lock-free</big>
-- <big>It's a classic pattern from purely functional data structures</big>
+- <big>It's the Michael-Scott queue, a classic concurrent FIFO design</big>
 
 The bit that matters most in practice:
 
-- <big>Backpressure metrics (queue length, active count) are lock-free reads of the atom's state</big>
+- <big>Queue length and active count are tracked in separate atoms</big>
 - <big>The server thread reads them every iteration of the accept loop</big>
-- <big>On Puma: take a mutex, or accept fuzzy stats</big>
-- <big>On Raptor: essentially free</big>
+- <big>Those reads do not acquire the queue's mutation lock, because there isn't one</big>
+- <big>The values are point-in-time snapshots; they can change immediately after being read</big>
+
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+
+---
+
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+
+## Scaling app threads without making CPU contention worse
+
+The pool stays fixed at `threads` unless you set `max_threads`.
+
+- <big>A native CRuby thread hook measures time running, blocked outside the GVL, and waiting for the GVL</big>
+- <big>The queue has to stay non-empty, and every current worker has to be active</big>
+- <big>Blocked time has to exceed half of worker time</big>
+- <big>GVL wait has to stay below two percent</big>
+- <big>Only then does the pool add a temporary thread, up to `max_threads`</big>
+- <big>When the queue drains, temporary threads leave and the pool returns to `threads`</big>
+
+The distinction matters. More threads help when requests are asleep in database or network calls. They make CPU-bound Ruby slower when the GVL is already the bottleneck.
+
+`max_threads: Float::INFINITY` allows the pool to grow without a fixed limit. That still does not make OS threads as cheap as fibers.
 
 <br>
 <br>
@@ -1281,7 +1310,7 @@ flowchart TB
     Col["Collector threads<br/>drain Ractor::Ports"]
     ATP["App thread pool<br/>calls Rack app<br/>writes response"]
 
-    Client -->|"SYN"| Srv
+    Client -->|"connected socket + request bytes"| Srv
     Srv -->|"fast path: complete on first read"| ATP
     Srv -->|"slow path: bytes not ready"| Rct
     Rct -->|"got bytes; hand raw buffer to pool"| RP
@@ -1369,8 +1398,8 @@ end
 
 - <big>Wait 1ms for the next request on the same connection</big>
 - <big>If bytes arrive in that window: parse and dispatch inline, on the same thread</big>
-- <big>Only bounce back to the reactor when the client actually stops sending</big>
-- <big>For clients that pipeline requests (browsers, gRPC-Ruby transports), this is a huge tail-latency win</big>
+- <big>Return to the reactor when no bytes arrive inside the 1ms window, or when a request is incomplete</big>
+- <big>The trade: occupy an app thread for up to 1ms to widen the no-reactor fast path</big>
 
 <br>
 <br>
@@ -1493,7 +1522,7 @@ Notable: a single HTTP/2 client connection in Raptor can have many streams in fl
 - <big>Each stream is a separate work item in the queue</big>
 - <big>Different streams from the same connection can end up on different app threads</big>
 - <big>Those threads still share the main GVL, so they overlap productively when the app is in I/O (the common Rails case), the same way Puma's keep-alive requests do</big>
-- <big>The parsing for each stream happens in the HTTP/2 Ractor pool on its own GVL, actually in parallel with the app work</big>
+- <big>On the reactor path, frame batches parse in the HTTP/2 Ractor pool on its own GVL, in parallel with app work</big>
 
 <br>
 <br>
@@ -1560,7 +1589,7 @@ The master needs to know what the workers are doing.
 - <big>How busy?</big>
 - <big>Have they crashed?</big>
 
-**Puma**: pipes. Workers write JSON messages every check interval. Master reads.
+**Puma**: pipes. Workers write status messages every check interval. Master reads.
 
 **Raptor**: anonymous shared memory via `mmap`.
 
@@ -1675,7 +1704,7 @@ flowchart TB
 
 - <big>Master calls `mmap` for the region **before** forking</big>
 - <big>Every worker inherits the mapping</big>
-- <big>Each worker writes a 49-byte slot every second: pid, phase, requests, backlog, busy threads, boot time, checkin time, booted flag</big>
+- <big>Each worker writes a 49-byte slot every second: pid, phase, requests, backlog, busy and available threads, boot time, checkin time, booted flag</big>
 - <big>Master reads the whole region directly. No JSON. No pipe drain. No signal.</big>
 - <big>`bundle exec raptor stats` prints the region as JSON, essentially instantly</big>
 
@@ -1760,9 +1789,10 @@ The problem:
 - <big>Default is a deterministic hash of the connection's four-tuple (client IP, client port, server IP, server port)</big>
   - Same four-tuple always lands on the same worker. Not random. Not round-robin.
   - Good spread on average across many clients, but no awareness of which worker is actually busy
-  - One client hammering from the same source port lands on the same worker every SYN
 
-The Linux answer since kernel 4.5: **attach a BPF program to the reuseport group** via the `SO_ATTACH_REUSEPORT_EBPF` socket option. Kernel runs your program on every incoming SYN to decide which listener wins.
+The Linux answer since kernel 4.5: **attach a BPF program to the reuseport group** via the `SO_ATTACH_REUSEPORT_EBPF` socket option. When the kernel selects a socket from that group for a new connection, your program can make the choice.
+
+Raptor uses this for plain `tcp://` listeners. TLS and Unix listeners continue to use sockets inherited from the master.
 
 <br>
 <br>
@@ -1791,9 +1821,9 @@ Puma has [`ClusterAcceptLoopDelay`](https://github.com/puma/puma/blob/master/lib
 - <big>Before each accept, a worker sleeps for a fraction of `max_delay` (default 5ms)</big>
 - <big>The sleep is proportional to the worker's own load: 0 when idle, `max_delay` when very busy</big>
 - <big>Every worker still accepts. Nobody refuses. Nobody gets skipped.</big>
-- <big>Busier workers wake later. Less-busy workers wake first and win the accept race on the shared `SO_REUSEPORT` listener.</big>
+- <big>Busier workers wake later. Less-busy workers wake first and win the accept race on the listener inherited from Puma's master.</big>
 
-It's clever, but the signal is a proxy for load, not the load itself. And it does the choosing in userspace, one worker sleeping past its turn. BPF does the choosing in the kernel with real numbers.
+It's clever, portable, and deliberately imprecise. Each worker only needs its own load. Raptor's BPF path instead publishes cluster-wide load to a kernel map and chooses before a worker calls `accept`.
 
 <br>
 <br>
@@ -1826,7 +1856,7 @@ It's clever, but the signal is a proxy for load, not the load itself. And it doe
   - No out-of-bounds memory access
   - Provably terminates
 - <big>If any of that can't be proved, the program is rejected at load time</big>
-- <big>Once loaded, runs at essentially zero overhead per event</big>
+- <big>Once loaded, runs inside the kernel without a userspace round-trip for each decision</big>
 
 Modern Linux observability (`bcc`, `bpftrace`, `cilium`, `perf`) is all built on this. It's genuinely one of the most exciting things that has happened to Linux in the last decade.
 
@@ -1854,25 +1884,26 @@ Modern Linux observability (`bcc`, `bpftrace`, `cilium`, `perf`) is all built on
 
 ```mermaid
 flowchart TB
-    Client(["client SYN"])
-    K["Kernel: reuseport group has 4 sockets"]
-    BPF["Raptor's BPF program<br/>reads load map"]
-    W0["Worker 0<br/>load = 5"]
-    W1["Worker 1<br/>load = 2 ← min"]
-    W2["Worker 2<br/>load = 8"]
-    W3["Worker 3<br/>load = 6"]
-
-    Client --> K
-    K -->|"which socket?"| BPF
-    BPF -->|"pick W1"| K
-    K -->|"deliver to W1's accept queue"| W1
+    Client(["new connection"])
+    Hash["connection hash"]
+    A["candidate A<br/>Worker 0, load 5"]
+    B["candidate B<br/>Worker 3, load 6"]
+    Pick["choose Worker 0<br/>reserve load 5 → 6"]
+    Queue["Worker 0 accept queue"]
+
+    Client --> Hash
+    Hash -->|"sample 1"| A
+    Hash -->|"sample 2"| B
+    A --> Pick
+    B --> Pick
+    Pick -->|"atomic increment, then route"| Queue
 ```
 
 - <big>Each worker has a **load reporter thread**</big>
 - <big>Publishes its current backlog into a BPF map every millisecond</big>
-- <big>BPF program reads all slots, finds the minimum</big>
-- <big>Loads within 1 of that minimum are treated as tied. That range from `min` to `min + 1` is what I call the **tie band**.</big>
-- <big>Ties are broken by the four-tuple hash. If nobody's in the tie band with the min, the min wins outright.</big>
+- <big>The connection hash picks two distinct workers</big>
+- <big>The BPF program compares those two load slots and chooses the lower one</big>
+- <big>That is **power of two choices**: near-global balance without scanning every worker</big>
 
 <br>
 <br>
@@ -1894,18 +1925,17 @@ flowchart TB
 <br>
 <br>
 
-## Why the tie band matters
+## Why the reservation matters
 
-- <big>Without it, a worker that briefly drains one request looks like the least-loaded worker</big>
-- <big>Every new SYN gets routed to it</big>
-- <big>By the time the next load-map update happens (1ms later), that worker is now the most loaded</big>
-- <big>You end up herding bursts onto whichever worker most recently reported the lowest load</big>
+The reporter only publishes once per millisecond. A burst can contain many connections.
 
-With the tie band:
+- <big>Without a reservation, every connection in that burst can observe the same stale low value</big>
+- <big>They can all choose the same worker before Ruby reports the new backlog</big>
+- <big>Raptor atomically increments the chosen BPF slot **before** routing</big>
+- <big>The next connection sees that reservation immediately</big>
+- <big>When Ruby accepts a socket, it also publishes `backlog + 1` rather than waiting for the reporter</big>
 
-- <big>Small differences don't cause herding</big>
-- <big>Load spreads across all near-idle workers via the four-tuple hash</big>
-- <big>Under bursts, the effect is measurable in the p95 latency numbers</big>
+The load number is partly measurement and partly admission ledger. That closes the stale-reporting window that caused herding in the earlier design.
 
 <br>
 <br>
@@ -1929,9 +1959,9 @@ With the tie band:
 
 ## BPF in Raptor, by the numbers
 
-- <big>The whole BPF program is about 70 lines of C</big>
+- <big>The whole BPF program is under 70 lines of C</big>
 - <big>Compiles down to a few hundred bytes of BPF bytecode</big>
-- <big>Runs in the kernel, on every incoming SYN</big>
+- <big>Runs in the kernel whenever the reuseport group selects a socket for a new connection</big>
 - <big>To load it from Ruby, I wrote **`libbpf-ruby`**</big>
   - `libbpf` is the standard C library that user-space programs use to load, verify and attach BPF programs
   - `libbpf-ruby` is my binding around it
@@ -1939,7 +1969,7 @@ With the tie band:
 
 Graceful fallback:
 
-- <big>If `libbpf-ruby` isn't installed, or the BPF object hasn't been compiled, Raptor silently falls back to the kernel's default four-tuple-hash routing</big>
+- <big>If `libbpf-ruby` isn't installed, or the BPF object hasn't been compiled, Raptor silently falls back to the listener inherited from the master</big>
 - <big>Everything still works. You just don't get load-aware routing.</big>
 - <big>If the kernel refuses the program (verifier error, missing features), startup raises. Loud failure, not silent misbehaviour.</big>
 
@@ -2180,9 +2210,9 @@ The libraries that came out of building Raptor:
 
 Each of them is small, focused, tested, and useful outside of Raptor.
 
-- <big>If you want lock-free primitives in Ruby, `atomic-ruby` is the fastest way in</big>
+- <big>If you want lock-free primitives in Ruby, `atomic-ruby` gives you a small, direct API</big>
 - <big>If you want to try Ractor-based parallelism without writing the coordination yourself, `ractor-pool` is that</big>
-- <big>If you want to load a BPF program from Ruby, `libbpf-ruby` is currently the only option</big>
+- <big>If you want to load a BPF program from Ruby, `libbpf-ruby` gives you a direct binding to libbpf</big>
 
 I didn't set out to build a small library ecosystem. It's what happens when you refuse to fold every helper back into the main gem.
 
@@ -2210,10 +2240,11 @@ I didn't set out to build a small library ecosystem. It's what happens when you
 
 Real numbers are in the [README benchmarks section](../README.md#micro-benchmarks). The shape:
 
-- <big>**IO-bound work**: Falcon wins by a wide margin. Its fibers keep every client connection in flight at once. Thread-based servers cap out at their pool size.</big>
-- <big>**CPU-bound HTTP/1.1**: Raptor beats Puma on both throughput and tail latency.</big>
+- <big>**IO-bound HTTP/1.1**: Scaling lifts Raptor from 3.11k to 8.63k req/s without keep-alive and from 3.21k to 9.43k with it. Falcon wins the first; Raptor wins the second.</big>
+- <big>**CPU-bound HTTP/1.1**: Fixed and scaling Raptor are effectively identical. Puma leads by 5% without keep-alive and less than 1% with it; Raptor leads Falcon.</big>
   - Tail latency ("p95") is the response time that 5% of requests exceed. It's what your slowest users see. Lower is better.
-- <big>**HTTP/2**: Raptor and Falcon both implement it. Puma doesn't.</big>
+- <big>**HTTP/2**: Scaling lifts Raptor from 1.14k to 4.46k req/s on IO and narrows Falcon's CPU-throughput lead from 27% to 14%. Falcon still leads throughput; Raptor has the lower CPU p95.</big>
+- <big>**Variance**: HTTP/1.1 is stable. HTTP/2 is noisy enough that I treat it as direction, not a precise ranking.</big>
 
 Different workloads, different winners. That's fine.