kino 0.1.0-x86_64-linux → 0.1.1-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20cd72c65cf1a45bba8cc7223e1a64ccf278368f76744abbd10b8a95e38c1000
-  data.tar.gz: 04c0301ecdb6df43ec1fb4a9eef8bd7d516c4b06a617c8184cc91f9c2c90cdeb
+  metadata.gz: 9404affa345dae0c084dbac9089a5171e27251577a9cac4c5d8259a47da786b2
+  data.tar.gz: 249ec9fd4807736290d656a95983da3a3d5d901bac8d6aef9f02cc0bdb0adf01
 SHA512:
-  metadata.gz: 002266ff4b79b89dbe1ec2042354245369ac93bbb44e2728b71bd4e1740196602f905bbf3635276c67d63f13928ff0ee137eb2591ee99d8bf344f4c9c3c8e9c1
-  data.tar.gz: b6d847e3dc68ddd936706628e8c331c511d1eb158e26f369a0fa52d749fff1412663fd1941609ffd49ffa217067c508a03447b86047cdd1e84d70ab86fc0391c
+  metadata.gz: e54a6f80e3dbc9a88bbef80678f53321750aeaa9de4316893a3195904d7b7fbd192450ecb6083898536c504111fb960eb3e5391f1053d4b5a3b5f59341b23fdc
+  data.tar.gz: 1248fd09e789e1301360d05a065b2a25c65f5256a92787b1b3b675d9db59ef571db0f0f05a2fe9e283cb3802442c4f2b121065be732544130e7d377a8d3ae60e

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.1.1] - 2026-06-11
+- Mode-dependent `threads` default: 1 per worker in :ractor mode (threads
+  inside a ractor share its lock and cost a per-request handoff; +16-18%
+  on fast handlers, measured on dedicated hardware), 3 in :threaded mode.
+  Explicit `threads` always wins; waiting-heavy ractor apps should raise
+  `workers` instead.
+- `queue_timeout` default raised from 1 to 5 seconds: a brief burst now
+  waits out the spike instead of shedding 503s within a second.
+
 ## [0.1.0] - 2026-06-11
 
 Initial release.

data/README.md

@@ -11,14 +11,15 @@ on every core in **one small process**. A **Rust** (tokio + hyper)
 front-end owns the network, parallel **Ractors** run your Rack 3 app,
 and a threaded fallback mode runs everything else, Rails included.
 
-* **Fast.** On a real 8-core server, every Kino mode is **1.4-2×** ahead
-  of a same-topology Puma cluster on I/O-light endpoints. Ractor mode
-  also wins on pure CPU. [Benchmarks](#benchmarks) below.
+* **Fast.** On a real 8-core server, every Kino mode is **1.5-2×**
+  ahead of a Puma fork cluster on I/O-light endpoints. Ractor mode also
+  wins on pure CPU, **30%+**. [Benchmarks](#benchmarks) below.
 * **A fraction of the memory.** One process instead of a fork per core:
-  about **1/19th of the Puma cluster's memory** under the same load, and
-  about 1/8th when serving the Rails hello-world.
-* **Parallel without forking.** Ractor mode runs CPU work **5×** faster
-  than Kino's own GVL-bound threaded mode, in the same small process.
+  about **15× less memory** than the Puma cluster under the same load,
+  and 8× less when serving the Rails hello-world.
+* **Parallel without forking.** Ractor mode runs CPU work **more than
+  5× faster** than Kino's own GVL-bound threaded mode, in the same
+  small process.
 * **Production plumbing included.** Graceful drain, crash supervision
   and respawn, bounded queues with 503 backpressure, request timeouts,
   TLS (rustls), live stats, async access and app logging.
@@ -64,62 +65,72 @@ notes live in [doc/architecture.md](doc/architecture.md).
 
 Measured on a real server: AWS **c7a.2xlarge** (8-core AMD EPYC 9R14,
 16 GB, Amazon Linux 2023). This is a realistic app-server size. The same
-Ractor-shareable app runs on every server, Ruby 4.0.5 with YJIT, equal
-topology (8 workers × 3 threads; Puma forks, Kino stays in one process).
+Ractor-shareable app runs on every server, Ruby 4.0.5 with YJIT, every
+server at its defaults: Puma forks 8 workers × 3 threads, Kino stays in
+one process (8 workers; 1 thread each in ractor modes, 3 in threaded).
 Numbers are req/s by wrk (8-second windows, 64 connections, same host).
 Methodology and the analysis behind every column:
 [doc/benchmarks.md](doc/benchmarks.md).
 
-| endpoint    | Kino :ractor | + lanes | Kino :threaded | Puma (cluster) |
-|-------------|-------------:|--------:|---------------:|---------------:|
-| /plaintext  |      201,472 | **241,501** |    218,348 |        117,838 |
-| /10k        |      156,635 | **183,564** |    153,442 |        106,666 |
-| /cpu (fib)  |       66,735¹| **70,373**  |     13,298 |         58,207 |
-| /io (5 ms)  |        4,527²|   4,530 |      **4,715** |          4,691 |
-| /io_native  |        4,714 | **4,717** |        4,709 |          4,692 |
+| endpoint    | Kino :ractor | + lanes | :ractor, `workers 32`² | Kino :threaded | Puma (cluster) |
+|-------------|-------------:|--------:|-----------------------:|---------------:|---------------:|
+| /plaintext  |      229,565 | **244,340** |         156,118 |        217,619 |        118,190 |
+| /10k        |      179,119 | **188,258** |         134,457 |        157,147 |        105,588 |
+| /cpu (fib)  |   **76,922**¹|  73,136 |          62,406 |         13,499 |         58,337 |
+| /io (5 ms)  |        1,548 |   1,548 |       **5,935** |          4,715 |          4,687 |
+| /io_native  |        1,570 |   1,571 |       **6,289** |          4,717 |          4,695 |
 
-Memory on the same box, RSS under load:
+Memory on the same box, RSS after sustained load:
 
 | serving               | Kino (one process) | Puma cluster (8 workers) |
 |-----------------------|-------------------:|-------------------------:|
-| bench app, :ractor    |          **57 MB** |                 1,078 MB |
-| bench app, :threaded  |          **50 MB** |                 1,078 MB |
+| bench app, :ractor    |          **80 MB** |                 1,256 MB |
+| bench app, :threaded  |         **151 MB**³|                 1,256 MB |
 | Rails hello-world     |          **97 MB** |                   797 MB |
 
 "+ lanes" is the experimental per-worker-queue dispatcher (`lanes true`).
-It adds +20% over the shared queue on this hardware and makes ractor
-mode the fastest Kino configuration. Details:
+It posts the fastest plaintext/10k of any configuration here. Details:
 [doc/benchmarks.md](doc/benchmarks.md#lane-dispatch-experimental-lanes-true).
 
 ¹ Stock settings, no tuning. Ractor mode beats the fork cluster on pure
-CPU by +15% (+21% with lanes). Threaded mode shows the GVL ceiling that
-every single-process Ruby server hits. The CPU-tuning recipe that our
-earlier Docker measurements needed makes no difference on real hardware
-(+0.5%); see [doc/benchmarks.md](doc/benchmarks.md#cpu-bound-tuning).
-
-² The ractor timer tax is small on real hardware: −4% against threaded
-mode (it was −18% in Docker). Wait-bound throughput is slots ÷ wait, and
-Kino slots are threads, not processes. `workers 32, threads 1` measured
-**5,922 /io (+27% over the cluster) and 6,254 /io_native (+34%)**, still
-one small process. See
+CPU by +32% (+25% with lanes). Threaded mode shows the GVL ceiling that
+every single-process Ruby server hits. The old CPU-tuning recipe is
+retired: its `threads 1` half **is** the default now, and its
+`tokio_threads 1` half costs −12% on real hardware; see
+[doc/benchmarks.md](doc/benchmarks.md#cpu-bound-tuning).
+
+² Wait-bound throughput is slots ÷ wait, and the default columns bring
+8 single-thread workers against the cluster's 24 threads. Kino slots
+are threads, not processes—when your app waits a lot, raise `workers`.
+The `workers 32` column is that tuning: **+27% over the cluster on /io
+(+34% via `Kino.sleep`)** while still ahead of it on pure CPU, all in
+one small process. The cost is the CPU-light rows (32 ractors
+oversubscribe 8 cores); pick the topology your app's wait profile
+needs. See
 [doc/benchmarks.md](doc/benchmarks.md#why-io-lags-in-ractor-mode-on-linux).
 
+³ With `MALLOC_ARENA_MAX=2` (the standard Ruby deployment setting;
+Heroku's default). Without it, 24 threads churning 10 KB responses
+through one glibc heap balloon to ~600 MB—an arena-fragmentation
+footgun, not a leak, and ractor mode sidesteps it. See
+[doc/benchmarks.md](doc/benchmarks.md#memory-under-load-and-the-glibc-arena-footgun).
+
 A common first idea is to keep your current server and wrap the app in
 a ractor pool. We measured that too (same box; the analysis is in the
 doc):
 
-| endpoint   | Kino :ractor | Puma + ractor wrapper | Falcon + ractor wrapper |
-|------------|-------------:|----------------------:|------------------------:|
-| /plaintext |  **201,472** |                19,425 |                 100,624 |
-| /cpu (fib) |   **66,735** |                17,106 |                  49,083 |
-| /io (5 ms) |    **4,527** |                 1,447 |                   1,549 |
-
-In short: ractor mode reaches fork-level CPU parallelism (**5×** Kino's
-own GVL-bound threaded mode) in one process, at about 1/19th of the
-cluster's memory. Every Kino mode is 1.4-2× ahead of the cluster on
-I/O-light endpoints. The macOS numbers (secondary; everything there hits
-the loopback ceiling) and the YJIT × Ractors gotcha are in
-[doc/benchmarks.md](doc/benchmarks.md).
+| endpoint   | Kino :ractor (8×3) | Puma + ractor wrapper | Falcon + ractor wrapper |
+|------------|-------------------:|----------------------:|------------------------:|
+| /plaintext |        **199,032** |                19,532 |                 100,342 |
+| /cpu (fib) |         **68,238** |                17,323 |                  48,561 |
+| /io (5 ms) |          **4,531** |                 1,452 |                   1,544 |
+
+In short: ractor mode beats fork-level CPU parallelism (**5.7×** Kino's
+own GVL-bound threaded mode, +32% over the cluster) in one process, at
+about 1/16th of the cluster's memory. Every Kino mode is 1.5-2.1×
+ahead of the cluster on I/O-light endpoints. The macOS numbers
+(secondary; everything there hits the loopback ceiling) and the
+YJIT × Ractors gotcha are in [doc/benchmarks.md](doc/benchmarks.md).
 
 Reproduce: `bench/run.sh [seconds] [concurrency]` for the main table,
 `bench/studies.sh` for the follow-ups (CPU recipe, topology, scaling,
@@ -174,10 +185,10 @@ server = Kino::Server.new(app,
   bind: "127.0.0.1",
   port: 9292,                 # 0 = ephemeral; read back via server.port
   workers: Etc.nprocessors,   # ractors (parallelism)
-  threads: 3,                 # threads per ractor (I/O concurrency, Puma-style)
+  threads: 1,                 # per worker; ractor default 1, threaded default 3
   mode: :auto,                # :auto | :ractor | :threaded
   queue_depth: 1024,          # bounded queue; overflow → 503
-  queue_timeout: 1.0,         # seconds before 503 on a full queue
+  queue_timeout: 5.0,         # seconds before 503 on a full queue
   request_timeout: nil,       # seconds before a slow response becomes a 504 (nil = off)
   shutdown_timeout: 30,       # drain deadline
   tls: { cert: "cert.pem", key: "key.pem" },  # file paths or inline PEM
@@ -210,7 +221,7 @@ kwargs and CLI flags > config file > defaults.
 # kino.rb
 port 9292
 workers 8
-threads 3
+threads 1
 mode :ractor
 ```
 
@@ -266,7 +277,7 @@ cost):
 
 ```ruby
 server.stats
-# => {mode: :ractor, lanes: false, workers: 8, threads: 3, batch: 1,
+# => {mode: :ractor, lanes: false, workers: 8, threads: 1, batch: 1,
 #     respawns: 0, queued: 0, in_flight: 2, served: 1041, rejected: 0,
 #     timeouts: 0}
 # plus lane_depths: [...] when lane dispatch is on
@@ -276,19 +287,20 @@ From the outside, `kill -USR1 <pid>` prints the same snapshot as one line
 (pair it with `pidfile` to find the pid):
 
 ```
-Kino stats: mode=:ractor lanes=false workers=8 threads=3 batch=1 respawns=0 queued=0 in_flight=2 served=1041 rejected=0 timeouts=0
+Kino stats: mode=:ractor lanes=false workers=8 threads=1 batch=1 respawns=0 queued=0 in_flight=2 served=1041 rejected=0 timeouts=0
 ```
 
 ## Logging
 
 With one log line per request, `Kino::Logger` sustained **2.4× the
-throughput of a shared `::Logger`** (151k vs 63k req/s on the benchmark
+throughput of a shared `::Logger`** (149k vs 63k req/s on the benchmark
 box). There are two native pieces. Both write through a lock-free
 channel to a Rust flusher thread, so request threads never take a log
 mutex and never make a write syscall:
 
 - **Access log** (`log_requests true`): one line per request to stdout,
-  including the 503s that never reach your app. On color terminals the
+  including the 503s that never reach your app. Recommended in
+  development; cheap enough for production. On color terminals the
   lines are tinted by status class: 2xx green, 3xx yellow, 4xx maroon,
   5xx bright red:
 

data/doc/benchmarks.md

@@ -27,9 +27,18 @@ the deployment most apps run today.
   plaintext 26-37% lower while leaving Puma's number unchanged.
 - Identical app for every server (`bench/bench_app.rb`), Ractor-shareable
   so Kino's `:ractor` mode can run it unmodified.
-- Topology held equal: Puma 8 forked workers × 3 threads vs Kino
-  8 workers × 3 threads in one process.
-- Follow-up studies (`bench/studies.sh`): CPU recipe, topology sweep,
+- Topology: each server at its shipped defaults—Puma 8 forked workers
+  × 3 threads (24 slots) vs Kino 8 workers in one process (× 1 thread
+  in ractor modes, the default since 0.1.1; × 3 threads in threaded
+  mode). Equal-topology numbers (Kino at 8×3) are in the studies below.
+- The headline tables also carry an io-tuned column (`workers 32,
+  threads 1`)—not a default, labeled as such—because the /io rows are
+  a slot-count story (see below).
+- The dataset spans three identical boxes: the original measurements,
+  a full re-measure at the 0.1.1 defaults, and the final headline
+  sweep. Equal-config numbers reproduced across boxes within ~1-2%
+  throughout.
+- Follow-up studies (`bench/studies.sh`): CPU tuning, topology sweep,
   /io worker scaling, logging costs, and memory—run in the same session
   as the headline tables.
 - The harness waits for the port to be genuinely free between targets.
@@ -46,41 +55,51 @@ the deployment most apps run today.
 ## Reading the headline tables
 
 - **Plaintext/10k**: Kino's tokio front-end clears the fork cluster by
-  1.4-2× (lanes plaintext 241,501 vs Puma 117,838 = 2.05×; the smallest
-  margin is threaded /10k at 1.44×). The cross-ractor handoff shows up
-  as ractor (201k) trailing threaded (218k) on trivial handlers—nothing
-  in them needs parallel Ruby—and lane dispatch reverses that (241k).
-- **CPU (recursive fib)**: ractor mode does **5× its own GVL-bound
-  threaded mode** (66,735 vs 13,298)—that's the entire point of
-  ractors—and beats the fork cluster outright: +15% with stock
-  defaults, +21% with lanes (70,373 vs 58,207).
-- **Memory**: serving the same loaded bench app, Kino held **57 MB
-  (ractor) / 50 MB (threaded)** where the 8-worker cluster held
-  **1,078 MB**—a fork per core pays one full copy of the VM, the app,
-  and its YJIT-compiled code per worker. On the Rails hello-world:
-  Kino 97 MB vs cluster 797 MB.
+  1.5-2.1× (lanes plaintext 244,340 vs Puma 118,190 = 2.07×; the
+  smallest margin is threaded /10k at 1.49×). At the old 3-thread
+  topology the cross-ractor handoff showed up as ractor trailing
+  threaded on trivial handlers; the 1-thread default reverses that
+  (ractor 230k vs threaded 218k) and lanes widen it (244k).
+- **CPU (recursive fib)**: ractor mode does **5.7× its own GVL-bound
+  threaded mode** (76,922 vs 13,499)—that's the entire point of
+  ractors—and beats the fork cluster outright: +32% with stock
+  defaults (+25% with lanes, 73,136 vs 58,337). Even the io-tuned
+  `workers 32` topology stays ahead of the cluster on CPU (62,406).
+- **Memory**: after serving the full endpoint battery, Kino held
+  **80 MB** (ractor or lanes, default topology) where the 8-worker
+  cluster held **1,256 MB**—a fork per core pays one full copy of the
+  VM, the app, and its YJIT-compiled code per worker. On the Rails
+  hello-world: Kino 97 MB vs cluster 797 MB. Threaded mode under the
+  same battery needs a malloc note; see
+  [Memory under load](#memory-under-load-and-the-glibc-arena-footgun).
 - **I/O (5 ms wait)**: all dispatch models tie within ~4% at equal slot
-  counts; the lever that matters is slot count, see
-  [below](#why-io-lags-in-ractor-mode-on-linux).
+  counts, so the default columns show the ractor modes behind on /io
+  (8 slots vs the cluster's 24), and the `workers 32` column shows the
+  same engine winning (+27%, +34% via `Kino.sleep`) once it has more
+  slots than the cluster. The lever is slot count, and Kino slots are
+  cheap: see [below](#why-io-lags-in-ractor-mode-on-linux).
 
 ## CPU-bound tuning
 
-On real hardware, Kino's stock defaults already lead the cluster on
-pure CPU—same-session studies run:
+On real hardware, Kino's stock defaults lead the cluster on pure
+CPU—and the old tuning recipe is now obsolete. Same-session studies
+run:
 
 | config | /cpu req/s |
 |---|---:|
-| Puma cluster (reference) | 58,376 |
-| Kino `workers 8, threads 3`, tokio auto (default) | 68,257 |
-| Kino `workers 8, threads 1, tokio_threads 1` (recipe) | 68,629 |
-
-The tuned recipe is a wash (+0.5%)—and it still costs plaintext
-(112,815 vs ~200k) and /io (1,532, 8 slots): on this hardware there is
-no reason to use it. **This is a finding that changed with the
-environment**: in the earlier Docker-on-Mac runs the recipe was worth
-+12%, because tokio threads and wake churn competed for oversubscribed
-virtualized cores. If you deploy into a constrained/virtualized
-environment, the recipe may still pay; measure there.
+| Puma cluster (reference) | 58,505 |
+| Kino `workers 8, threads 3` (the default before 0.1.1) | 67,111 |
+| Kino `workers 8, threads 1, tokio_threads 1` (the old recipe) | 68,638 |
+| Kino `workers 8, threads 1`, tokio auto (**the default**) | **78,175** |
+
+The `threads 1` half of the old recipe became the default; the
+`tokio_threads 1` half now *costs* −12% on /cpu (and still costs
+plaintext: 107,743 vs 230k). Don't pin tokio threads. **The recipe's
+history is an environment story**: in the earlier Docker-on-Mac runs it
+was worth +12%, because tokio threads and wake churn competed for
+oversubscribed virtualized cores; on dedicated cores the same pin
+starves the I/O front-end instead. If you deploy into a
+constrained/virtualized environment, measure there.
 
 Two findings that survived the environment change:
 
@@ -99,8 +118,9 @@ Parallelism for CPU-bound Ruby comes from ractors or forks, nothing else.
 
 ## Why /io lags in ractor mode on Linux
 
-On bare metal the gap is small: ractor /io 4,527 vs threaded 4,715
-(−4%). In Docker it was −18%, and a pure-Ruby probe there measured
+On bare metal the gap is small at equal slot counts: ractor /io 4,531
+vs threaded 4,725 (−4%, both at 8×3). In Docker it was −18%, and a
+pure-Ruby probe there measured
 `sleep(0.005)` waking +2.3-2.8 ms late inside ractors vs +1.8 ms on the
 main ractor—non-main-ractor timer wakeups are coarser in Ruby 4.0, but
 how much that costs depends heavily on the kernel/virtualization stack.
@@ -110,14 +130,19 @@ A follow-up probe showed `IO.select`-style waits are tighter than
 **Mitigation 1—`Kino.sleep`:** releases the GVL and waits on the OS
 clock directly (chunked, so `Thread#kill`/shutdown stay responsive). The
 `/io_native` endpoint (same 5 ms wait via `Kino.sleep` when available)
-erases the remaining ractor gap on this box: 4,714 vs 4,527 plain sleep.
-
-**Mitigation 2—add workers; they're nearly free.** Wait-bound
-throughput is simply `slots ÷ effective wait`, and Kino's slots cost ~a
-thread each, not a forked process: `workers 32, threads 1` measured
-**5,922 /io (+27% over the 24-thread cluster's 4,672) and 6,254
-/io_native (+34%)**, still one small process. A fork cluster buying the
-same 32 slots pays for them in full copies of the app.
+erases the remaining ractor gap on this box: 4,721 vs 4,531 plain sleep.
+
+**Mitigation 2—add workers; they're nearly free.** The headline tables
+show default ractor-mode /io at 1,548: that's 8 slots (the 1-thread
+default) against the cluster's 24, because wait-bound throughput is
+simply `slots ÷ effective wait`. Kino's slots cost ~a thread each, not
+a forked process: the `workers 32, threads 1` column measured **5,935
+/io (+27% over the 24-thread cluster's 4,687) and 6,289 /io_native
+(+34%)**, still one small process, and still +7% ahead of the cluster
+on pure CPU. Its cost is the CPU-light rows (156k plaintext vs 230k at
+8×1: 32 ractors oversubscribe 8 cores). A fork cluster buying the same
+32 slots pays for them in full copies of the app; Kino pays in
+scheduler churn only where the cores are already saturated.
 
 ## The ractor-pool-wrapper comparison
 
@@ -127,11 +152,11 @@ already run. `bench/ractor_wrapper.rb` is that experiment, benchmarked on
 Puma and Falcon—not as a comparison of those servers, but to measure
 what the Rack-level hop itself costs (c7a.2xlarge, same session):
 
-| endpoint   | Kino :ractor | Puma + wrapper | Falcon + wrapper |
-|------------|-------------:|---------------:|-----------------:|
-| /plaintext |      201,472 |         19,425 |          100,624 |
-| /cpu (fib) |       66,735 |         17,106 |           49,083 |
-| /io (5 ms) |        4,527 |          1,447 |            1,549 |
+| endpoint   | Kino :ractor (8×3) | Puma + wrapper | Falcon + wrapper |
+|------------|-------------------:|---------------:|-----------------:|
+| /plaintext |            199,032 |         19,532 |          100,342 |
+| /cpu (fib) |             68,238 |         17,323 |           48,561 |
+| /io (5 ms) |              4,531 |          1,452 |            1,544 |
 
 Inside the Rack contract, the wrapper must reduce the env to a shareable
 subset, copy it to the worker ractor, copy the response back, and hold a
@@ -190,6 +215,32 @@ needs its `disable_initial_exec_tls` build flag just to load (dlopen +
 initial-exec TLS = `cannot allocate memory in static TLS block`)—one
 more reason to prefer mimalloc in dlopen'd extensions.
 
+## Memory under load (and the glibc arena footgun)
+
+RSS after serving the full endpoint battery (8 s each of /plaintext,
+/10k, /cpu, /io—a "warmed production process", not a fresh boot, which
+measures 26-27 MB for every Kino mode):
+
+| config | RSS loaded |
+|---|---:|
+| Kino :ractor 8×1 (default) | **80 MB** |
+| Kino lanes 8×1 | **80 MB** |
+| Kino :ractor 8×3 | 115 MB |
+| Kino :threaded 8×3 | 612 MB¹ |
+| Puma cluster 8×3 | 1,256 MB |
+
+¹ Not a leak: glibc malloc arena bloat. One 8-second /10k round takes
+threaded mode from 69 MB to ~800 MB and it never returns—24 threads
+churning 10 KB strings through one process heap is the textbook glibc
+arena-fragmentation case (the reason Rails ops set `MALLOC_ARENA_MAX=2`;
+Heroku ships that default). With `MALLOC_ARENA_MAX=2` the same battery
+ends at **151 MB** with throughput unchanged (165,993 vs 157,177 /10k,
+if anything faster). Ractor mode sidesteps the worst of it without any
+env tweak—objects live in per-ractor heaps, and repeated runs landed at
+80-124 MB regardless of arena settings. Puma's 1,256 MB barely moves
+under the cap (1,237 MB): its cost is eight full copies of the warmed
+VM, not arenas.
+
 ## Run-to-run variance (a.k.a. "is this a regression?")
 
 Rule of thumb from chasing this twice: never compare numbers from
@@ -197,21 +248,32 @@ different sessions; interleave A/B rounds in one session instead. The
 Docker-on-Mac environment swung ±10% on /cpu between sessions with the
 VM's mood; the dedicated c7a box is far steadier (same-session repeats
 land within ~1-2%), but the discipline stays—every comparative claim in
-these docs comes from same-session pairs.
+these docs comes from same-session pairs. Cross-box repeatability got
+its own test: the dataset was measured across three identical
+c7a.2xlarge boxes, and equal-config throughput numbers matched within
+~1-2% (loaded-RSS measurements swing far more with heap-growth
+timing—treat memory numbers as ballpark). The same discipline caught one fluke: a sweep round once
+posted threaded plaintext 28% low; interleaved re-runs minutes later
+put it back—suspect cells get re-measured, not published.
 
 ## Topology notes
 
-Measured on c7a.2xlarge, plaintext, ractor mode, same session: `8×3`
-(workers×threads) = 199,470, `8×1` = **232,469 (+17%)**, `16×1` =
-214,284. Threads inside one ractor share its lock, so every request
-handled by a 3-thread ractor pays a lock handoff that a 1-thread ractor
-doesn't (`perf` in the earlier Docker sessions attributed ~10% of cycles
-to `rb_native_mutex_unlock`/`thread_sched_wakeup_next_thread` at 8×3;
-the +17% reproduces exactly on real hardware). Threads-per-ractor exist
-for handlers that block on I/O; if yours don't, run `threads 1` and let
-workers = cores do the parallelism. (16×1 being worse than 8×1 also says
-the shared MPMC queue is *not* the bottleneck—8 extra parked consumers
-just add scheduler churn.)
+Measured on c7a.2xlarge, plaintext, ractor mode, same session (three
+interleaved rounds, medians): `8×3` (workers×threads) = 200,048, `8×1`
+= **232,173 (+16%)**, `16×1` = 214,570. Threads inside one ractor share
+its lock, so every request handled by a 3-thread ractor pays a lock
+handoff that a 1-thread ractor doesn't (`perf` in the earlier Docker
+sessions attributed ~10% of cycles to
+`rb_native_mutex_unlock`/`thread_sched_wakeup_next_thread` at 8×3; the
+gain reproduced on two separate boxes, +16-17% each). **This is why
+`threads` defaults to 1 in ractor mode since 0.1.1** (/cpu gains +18%
+the same way: 80,409 vs 68,132). The trade-off is /io at low worker
+counts: 1,534 at 8×1 vs 4,486 at 8×3—threads-per-ractor exist for
+handlers that block on I/O. If yours wait a lot, raise `workers`
+instead (32×1 beats even the 24-slot cluster, see above); slots are
+cheap. (16×1 being worse than 8×1 on plaintext also says the shared
+MPMC queue is *not* the bottleneck—8 extra parked consumers just add
+scheduler churn.)
 
 ## What profiling tried and rejected
 
@@ -239,23 +301,27 @@ safeguards: lane depth is capped at 4, and workers steal from siblings
 before parking (plus on every park tick), so a slow request can't strand
 its lane's backlog.
 
-Same-session A/B on c7a.2xlarge (ractor mode):
+Same-session A/B on c7a.2xlarge, ractor mode at the default topology
+(8×1):
 
 | endpoint | shared queue | lanes | delta |
 |----------|-------------:|------:|------:|
-| /plaintext | 201,472 | **241,501** | **+20%** |
-| /10k | 156,635 | 183,564 | +17% |
-| /cpu | 66,735 | 70,373 | +5% |
-| /io | 4,527 | 4,530 | flat |
-
-On this hardware lanes make ractor mode the fastest Kino configuration
-outright—+11% over threaded mode's plaintext, where the shared queue
-trails it. (On loopback-bound macOS, lanes lose a few percent instead;
-see the secondary table below.) It stays opt-in for now because overload
-semantics differ from the shared queue (`queue_depth` doesn't apply;
-capacity is lanes × 4 with brief dispatcher retries up to
-`queue_timeout` before the 503), and crash semantics, stealing fairness,
-and drain behavior have spec coverage but not production mileage.
+| /plaintext | 230,547 | **250,395** | **+9%** |
+| /10k | 182,788 | 198,301 | +8% |
+| /cpu | **78,175** | 73,345 | −6% |
+| /io | 1,550 | 1,550 | flat |
+
+Lanes' margin shrank with the move to 1-thread workers (at the old 8×3
+it was +21% plaintext: 240,193 vs 199,032 in the same session)—most of
+the futex pain lanes were built to avoid came from thread handoffs
+inside each ractor, and the new default removes those for everyone. At
+the default, lanes still post the fastest plaintext/10k of any Kino
+configuration, but plain shared-queue now takes /cpu. It stays opt-in because overload semantics differ from the
+shared queue (`queue_depth` doesn't apply; capacity is lanes × 4 with
+brief dispatcher retries up to `queue_timeout` before the 503), and
+crash semantics, stealing fairness, and drain behavior have spec
+coverage but not production mileage. (On loopback-bound macOS, lanes
+lose a few percent instead; see the secondary table below.)
 
 ## Logging costs
 
@@ -265,11 +331,11 @@ typical costs):
 
 | case (8×3, same session) | req/s |
 |---|---:|
-| threaded, no logging | 217,113 |
-| threaded, `log_requests true` (native access log) | 193,200 (−11%) |
-| ractor, access log off / on | 198,624 / 183,565 (−8%) |
-| app logs 1 line/req via shared `::Logger` (file) | **62,962** |
-| app logs 1 line/req via `Kino::Logger` (file) | **150,810 (2.4×)** |
+| threaded, no logging | 217,377 |
+| threaded, `log_requests true` (native access log) | 193,493 (−11%) |
+| ractor, access log off / on | 200,478 / 184,357 (−8%) |
+| app logs 1 line/req via shared `::Logger` (file) | **62,917** |
+| app logs 1 line/req via `Kino::Logger` (file) | **149,237 (2.4×)** |
 
 The shared-`::Logger` cost is the mutex: 24 worker threads serialize
 through one lock plus a write syscall per line. `Kino::Logger` hands the

data/doc/why-kino.md

@@ -15,8 +15,8 @@ deep-copies it, and sockets cannot cross at all.
 
 We measured what the "obvious" workaround costs. The ractor-pool wrapper
 experiment (reduce the env to a shareable subset, copy it to a worker
-over a `Ractor::Port`, copy the response back) runs at **19k req/s where
-Kino does 201k** on the same hardware—see the
+over a `Ractor::Port`, copy the response back) runs at **19.5k req/s
+where Kino does 199k** on the same hardware—see the
 [wrapper comparison](benchmarks.md#the-ractor-pool-wrapper-comparison).
 Copying at the Rack layer eats the entire ractor dividend. Dispatch has
 to live below the Rack contract.
@@ -78,10 +78,10 @@ objects; Rust sees one queue and one registry.
 
 With the dispatch cost eliminated, Ractors deliver the thing they were
 built for—a lock per ractor instead of one GVL—and each layer is
-visible in the [benchmarks](benchmarks.md): `/cpu` at 66.7k req/s in
-ractor mode vs **13.3k threaded (5×, the GVL ceiling)**, matching the
-fork cluster's CPU parallelism while holding **57 MB against the
-cluster's 1,078 MB**, because eight ractors share one VM, one Rust
+visible in the [benchmarks](benchmarks.md): `/cpu` at 76.9k req/s in
+ractor mode vs **13.5k threaded (5.7×, the GVL ceiling)**, beating the
+fork cluster's CPU parallelism by +32% while holding **80 MB against
+the cluster's 1,256 MB**, because eight ractors share one VM, one Rust
 front-end, one queue, and one JIT, where eight forks each pay full
 price.
 

data/lib/kino/configuration.rb

@@ -12,10 +12,10 @@ module Kino
       bind: "127.0.0.1",
       port: 0,
       workers: nil, # resolved to Etc.nprocessors in #to_h
-      threads: 3,
+      threads: nil, # resolved per mode in Server: 1 in :ractor, 3 in :threaded
       mode: :auto,
       queue_depth: 1024,
-      queue_timeout: 1.0,
+      queue_timeout: 5.0,
       request_timeout: nil,
       batch: 1,
       lanes: false,
@@ -144,7 +144,8 @@ module Kino
       # Worker count (ractors in :ractor mode); defaults to CPU cores.
       def workers(count) = @config.set(:workers, Integer(count))
 
-      # Threads per worker (I/O concurrency inside one ractor).
+      # Threads per worker (I/O concurrency inside one ractor); default is
+      # mode-dependent: 1 in :ractor mode, 3 in :threaded.
       def threads(count) = @config.set(:threads, Integer(count))
 
       # Dispatch mode: :auto, :ractor, or :threaded.

data/lib/kino/server.rb

@@ -41,8 +41,12 @@ module Kino
       @bind = settings[:bind]
       @requested_port = settings[:port]
       @workers = Integer(settings[:workers])
-      @threads = Integer(settings[:threads])
       @mode = resolve_mode(settings[:mode])
+      # Default threads per mode: 1 in :ractor (threads inside a ractor
+      # share its lock; a measured +17% on fast handlers; raise `workers`
+      # for I/O concurrency instead), 3 in :threaded (threads ARE the
+      # concurrency there).
+      @threads = Integer(settings[:threads] || ((@mode == :ractor) ? 1 : 3))
       @queue_depth = Integer(settings[:queue_depth])
       @queue_timeout_ms = (Float(settings[:queue_timeout]) * 1000).round
       @request_timeout_ms = settings[:request_timeout] ? (Float(settings[:request_timeout]) * 1000).round : 0

data/lib/kino/templates/kino.rb.tt

@@ -1,141 +1,110 @@
-# frozen_string_literal: true
-
 # Kino configuration.
 # Generated by `kino --init`.
 #
-# Every setting below is shown with its default value, commented out:
-# the file is a valid no-op until you uncomment something. Precedence:
-# explicit Server.new kwargs / CLI flags > this file > built-in defaults.
+# Every setting is shown with its default value and commented out, so
+# this file works as-is: uncomment what you want to change.
+# Command-line flags beat this file; this file beats built-in defaults.
 
 ## Network
 
-# Address to listen on. Use "0.0.0.0" to accept non-local connections.
+# Address to listen on. Use "0.0.0.0" to accept connections from other
+# machines.
 # bind "127.0.0.1"
 
-# Port to listen on. 0 picks an ephemeral port (readable via server.port).
-# The `kino` CLI defaults this to 9292 when nothing else sets it.
+# Port to listen on.
 # port 9292
 
-# TLS termination (rustls, in Rust; never blocks a Ruby thread).
-# Values are file paths or inline PEM strings. ALPN is http/1.1.
+# Serve HTTPS. Point these at your certificate and key files (inline
+# PEM strings also work).
 # tls cert: "config/certs/server.pem", key: "config/certs/server.key"
 
 ## Topology
 
-# Puma-style two-level topology: `workers` × `threads`.
-#
-# In :ractor mode, `workers` is the number of worker Ractors: true
-# multi-core parallelism for Ruby CPU work, one per core is a good start.
-# In :threaded mode the same total (workers × threads) runs as plain
-# Threads on the main ractor.
-
-# Defaults to the number of CPU cores (Etc.nprocessors).
+# How many workers to run. Each worker handles requests independently;
+# in :ractor mode every worker runs Ruby in parallel on its own core.
+# Default: one per CPU core.
 # workers 8
 
-# Threads per worker. Threads inside one ractor share its lock, so they
-# only add concurrency where handlers block on I/O (database calls, HTTP).
-# CPU-bound apps gain nothing past 1 (and pay a lock-handoff tax: threads 1
-# measured +17% on fast handlers). I/O-heavy apps want more SLOTS overall -
-# in :ractor mode prefer raising `workers` over `threads` (slots are cheap,
-# no fork memory): 32 workers x 1 thread beat 8x3 by +35% on waits.
-# threads 3
+# Threads inside each worker. More threads help when your app spends
+# time waiting on databases or other services; they do not make Ruby
+# code run faster. Left unset, Kino picks a sensible default for the
+# mode. If your app waits a lot in :ractor mode, prefer raising
+# `workers` instead.
+# threads 1
 
 ## Dispatch mode
 #
-# :auto:     :ractor when the app is Ractor-shareable, else :threaded
-#             (with a warning). Note: a Class used as a Rack app always
-#             counts as "shareable" even if calling it touches unshareable
-#             state; force :threaded for those.
-# :ractor:   require a Ractor-shareable app; raises
-#             Kino::UnshareableAppError otherwise. The app must capture
-#             nothing mutable: frozen middleware, Ractor.shareable_proc
-#             endpoints.
-# :threaded: run ANY Rack app (Rails included) on a classic thread pool.
+# :auto     - picks :ractor when your app supports it, else :threaded.
+# :ractor   - runs Ruby in parallel on all cores. Your app must be
+#             Ractor-shareable; check yours with `kino --check`.
+# :threaded - works with any Rack app, including Rails.
 # mode :auto
 
 ## Backpressure
 
-# Bounded request queue between the Rust front-end and Ruby workers.
-# When it stays full past queue_timeout, clients get an immediate 503
-# instead of waiting forever.
+# How many requests may wait in line. When the line stays full, new
+# requests are turned away with a 503 instead of waiting forever.
 # queue_depth 1024
 
-# Seconds a request may wait for queue space before the 503.
-# queue_timeout 1.0
+# How long (in seconds) a request may wait for a free spot before
+# getting the 503.
+# queue_timeout 5.0
 
-# Seconds the app gets to produce a response before the client receives a
-# 504 instead. Off by default (nil = wait forever). The handler is NOT
-# killed - its late response is dropped and its slot stays busy until it
-# returns, so size this above your slowest legitimate endpoint.
+# Give up on a response after this many seconds: the client gets a 504
+# while your app finishes in the background. Off unless set. Set it
+# above your slowest legitimate endpoint.
 # request_timeout 30
 
-# Requests a worker may grab per queue visit. Values above 1 squeeze more
-# throughput out of uniformly fast handlers, but add head-of-line blocking
-# behind slow ones and stretch the effective queue depth - leave at 1
-# unless your handlers are all sub-millisecond.
+# How many requests a worker grabs from the line at once. Leave at 1
+# unless all your endpoints are uniformly fast.
 # batch 1
 
-# EXPERIMENTAL lane dispatch: per-worker queues with awake-preferring
-# assignment and work stealing. Cuts per-request wakeups for uniformly
-# fast handlers; semantics under overload are slightly different (per-lane
-# caps with brief dispatcher retries instead of one global queue).
+# Experimental dispatcher that gives each worker its own line. Faster
+# for quick handlers; behavior under heavy overload differs slightly.
 # lanes false
 
-# Native access log: one line per request to stdout, written by a
-# Rust-side flusher thread - request threads never block on the log.
-#
-# On color terminals lines are tinted by status class (2xx green,
-# 3xx yellow, 4xx maroon, 5xx bright red). This is the SERVER's view - it
-# includes the 503 rejections your app never sees - and it interleaves
-# cleanly with your app's own log (e.g. Rails') on stdout. See also
-# Kino::Logger for routing the app log through the same async sink.
-#
-# Try enabling it in the development environment.
+# Print one line per request to stdout, colored by status on a
+# terminal. This is the server's view: it includes requests your app
+# never saw, such as 503s. Recommended in development.
 # log_requests false
 
 ## Lifecycle
 
-# Graceful-shutdown drain deadline in seconds: in-flight requests get this
-# long to finish; past it, their clients receive 500s and workers are
-# reaped. A second INT/TERM force-exits immediately.
+# On shutdown, give in-flight requests this many seconds to finish.
+# A second Ctrl-C (or signal) force-exits immediately.
 # shutdown_timeout 30
 
-# Write the master PID here on start; removed on graceful shutdown.
+# Write the server's process id to this file on start.
 # pidfile "tmp/pids/kino.pid"
 
 ## Runtime
 
-# Threads for the tokio (Rust I/O) runtime. Default (nil) lets tokio use
-# one per core: right for I/O-heavy apps. For CPU-heavy apps this is a
-# real lever: `tokio_threads 1` + `threads 1` measured +26% on a pure-CPU
-# benchmark (every spare thread is Ruby work you didn't run).
+# Threads for the Rust I/O engine. The default suits most apps; for
+# heavily CPU-bound apps, try 1 to leave more cores for Ruby.
 # tokio_threads 4
 
 ## App
 
-# Rackup file the `kino` CLI loads (positional CLI argument wins).
+# Rackup file to load (a command-line argument wins).
 # rackup "config.ru"
 
-# Sets RACK_ENV (unless already set) before the app is loaded by the CLI.
+# Sets RACK_ENV before the app is loaded, unless already set.
 # environment "production"
 
 ## Rails
 #
-# Rails runs on Kino TODAY in :threaded mode; uncomment for a Rails app:
+# Rails runs on Kino today in :threaded mode:
 #
 #   mode :threaded
 #   environment "production"
 #   threads 5                 # match your database pool size
 #
-# Recommended Rails-side settings to pair with Kino:
-#   - config.eager_load = true and no code reloading (production defaults):
-#     Kino's workers serve concurrently; lazy class loading under
-#     concurrency is slow and, in ractor mode, unsafe.
-#   - Database pool >= workers × threads (config/database.yml `pool:`).
-#   - Rails.logger goes to stdout/stderr or a thread-safe device.
+# Rails-side tips:
+#   - Run with eager loading and no code reloading (the production
+#     defaults).
+#   - Set the database pool to at least workers x threads.
+#   - Send logs to stdout or another thread-safe destination.
 #
-# Rails main is being ractorized, but
-# Rails.application still captures unshareable state at boot; known
-# blockers are documented in Kino's README. Track rails/rails main; when
-# Ractor.make_shareable(Rails.application) succeeds, `mode :ractor` here
-# is all you'll need to change.
+# Ractor mode cannot run Rails yet; the blockers are upstream in Rails.
+# Once `Ractor.make_shareable(Rails.application)` works, switching to
+# `mode :ractor` here is all you will need.

data/lib/kino/version.rb

@@ -2,5 +2,5 @@
 
 module Kino
   # The gem version (single source of truth; ext/kino/Cargo.toml syncs).
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kino
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: x86_64-linux
 authors:
 - Yaroslav Markin