turbo_tests2 3.2.16 → 3.2.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ba760f9553f5ac9180f943b7b6ba4292f8e3ae332c2ee8f93d704fb6df39fd8
-  data.tar.gz: 308a01984a1da21ef5a1005cd5f333404b8132b6b8b12717f9fcf1e6b213421d
+  metadata.gz: 4d0f84a37aeb74853501933d16cd9476a1f82800b3d33e9da544af8ef0e0c145
+  data.tar.gz: 581d982f38436235925c6bc8180a4ac29513c198599ae841949e47bce114186f
 SHA512:
-  metadata.gz: d15f6b3dc4601510f2fc2785b722b966fe543352a2408f084160e9b0d064fcf020cb234dbcc22b7c03baca495d1a7c87a13d41e24e74084a4bc43b6fe4aec5ac
-  data.tar.gz: be13e868955aacabb64993bab93050538def66c7c341406b082878d9f06d8c3098c701052f40c1e1a7c36eed026de5bc1c6930c7db42ab2e109a8240944c5d48
+  metadata.gz: 9d0f7b4e2080fd36f4da47ff4bdebed7fce369995e9c1b6cb305bc2caf9ad935ec2d65eaa84483721b361c57a12eb24b36fd3d0c5fc0ce16a62638f14df16636
+  data.tar.gz: ffc015acc34a5ad4658a2a5aa53ceb02ec6621eea4e625bc1a7d2b6558c1cc728037ad984c32cc52e08108f8c322011dee41926dfdde3400c5c65ae7021c82dc

data/CHANGELOG.md

@@ -30,6 +30,19 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.2.17] - 2026-10-14
+
+- TAG: [v3.2.17][3.2.17t]
+- COVERAGE: 95.94% -- 993/1035 lines in 11 files
+- BRANCH COVERAGE: 83.86% -- 265/316 branches in 11 files
+- 39.42% documented
+
+### Changed
+
+- README: document the spawn-based (fork-free) worker architecture that makes parallel workers engine-portable to JRuby and TruffleRuby, and add a Resource-Constrained CI (JVM Engines) section with the canonical 2-worker + capped-heap + raised-watchdog setup, matching the kettle-jem CI templates
+
+- Stall diagnostics and in-code docs now explain silent worker death: the 900s silence warning and the watchdog stall path point at the OOM killer as the most common cause of total silence in a parallel lane (spawned workers, JVM engines defaulting to 1/4 RAM heap each), with the fix inline (TURBO_TESTS2_MAX_PROCESSES=2 + capped heap); start_subprocess and max_processes_from_environment document the spawn-based engine-portable architecture
+
 ## [3.2.16] - 2026-10-14
 
 - TAG: [v3.2.16][3.2.16t]
@@ -761,7 +774,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.16...HEAD
+[Unreleased]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.17...HEAD
+[3.2.17]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.16...v3.2.17
+[3.2.17t]: https://github.com/galtzo-floss/turbo_tests2/releases/tag/v3.2.17
 [3.2.16]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.15...v3.2.16
 [3.2.16t]: https://github.com/galtzo-floss/turbo_tests2/releases/tag/v3.2.16
 [3.2.15]: https://github.com/galtzo-floss/turbo_tests2/compare/v3.2.14...v3.2.15

data/README.md

@@ -384,6 +384,60 @@ count at the number of discovered test groups.
 Known coverage formatter chatter remains collapsed into the concise coverage
 summary.
 
+### Resource-Constrained CI (JVM Engines)
+
+Worker parallelism is spawn-based, not fork-based: each worker is started as a
+real subprocess (`Process.spawn` / `Open3.popen3`), never `Kernel#fork`. That
+makes parallel workers engine-portable — MRI, JRuby, and TruffleRuby all run
+the same spawn-based pool, and the default worker count is the machine's core
+count (`Etc.nprocessors`) on every engine. There is no serial-only mode for
+JVM engines unless you ask for one with `TURBO_TESTS2_MAX_PROCESSES=1`.
+
+The cost of that portability on JVM engines is memory: each JRuby or
+TruffleRuby worker is a full JVM subprocess, and JRuby defaults its heap to
+one quarter of machine RAM. On a CI runner, `Etc.nprocessors` workers each
+grabbing a quarter of RAM is a recipe for the kernel's OOM killer, which kills
+workers **silently** — every worker stops messaging at once, and the stall
+watchdog then reports total silence. This is a resource problem, not a
+parallelism problem.
+
+The fix is to run fewer, smaller workers. This is the canonical
+resource-constrained setup, and the `kettle-jem` CI templates bake it into
+every JRuby workflow they generate:
+
+```bash
+TURBO_TESTS2_MAX_PROCESSES=2 \
+JRUBY_OPTS="-J-Xmx1280m" \
+TURBO_TESTS2_WATCHDOG_SECONDS=1500 \
+bundle exec turbo_tests2
+```
+
+Or in a GitHub Actions workflow:
+
+```yaml
+env:
+  # Fewer, smaller JVM workers on constrained runners.
+  TURBO_TESTS2_MAX_PROCESSES: 2
+  # Cap each worker JVM's heap (JRuby default: 1/4 of runner RAM).
+  JRUBY_OPTS: "-J-Xmx1280m"
+  # JVM lanes are slow; give the watchdog room without hitting the job timeout.
+  TURBO_TESTS2_WATCHDOG_SECONDS: 1500
+```
+
+Guidance:
+
+- **Cap workers** (`TURBO_TESTS2_MAX_PROCESSES=2`) when each worker is a heavy
+  process: JVM engines, large test suites, or shared/undersized runners. Two
+  JVM workers still roughly halve wall-clock time versus one.
+- **Cap the heap** (`JRUBY_OPTS="-J-Xmx1280m"`, or your engine's equivalent)
+  so total memory is bounded regardless of runner size.
+- **Raise the watchdog** (1500s) on slow engines: JIT warmup and heavy GC make
+  silence windows longer, and you want the watchdog report, not the provider
+  timeout, when something genuinely hangs.
+- The same knobs apply to any engine where a worker process is expensive —
+  the principle is: bound `workers × per-worker memory` under the runner's
+  capacity.
+
 ### Stall watchdog
 
 If the worker message queue goes silent — every worker alive but none

data/lib/turbo_tests/cli.rb

@@ -243,6 +243,16 @@ module TurboTests
       ]
     end
 
+    # Inclusive ceiling on the worker pool when neither --count nor --workers
+    # is passed. Explicit CLI counts always win. Two main uses:
+    #
+    # 1. Outer orchestrators (kettle-family) budgeting a machine-wide process
+    #    pool across concurrent family jobs.
+    # 2. Resource-constrained CI, where each worker is an expensive process —
+    #    JVM engines (JRuby, TruffleRuby) spawn a full JVM per worker, so cap
+    #    the pool (typically 2) AND the per-worker heap (e.g. JRUBY_OPTS=
+    #    "-J-Xmx1280m") to stay under runner RAM. See README
+    #    "Resource-Constrained CI (JVM Engines)".
     def max_processes_from_environment
       value = ENV.fetch("TURBO_TESTS2_MAX_PROCESSES", "").strip
       return if value.empty?

data/lib/turbo_tests/runner.rb

@@ -408,6 +408,14 @@ module TurboTests
       )
     end
 
+    # Spawns one worker as a real OS subprocess via Open3.popen3 — never
+    # Kernel#fork. This is what makes the worker pool engine-portable: MRI,
+    # JRuby, and TruffleRuby all spawn subprocesses the same way, and the
+    # default pool size is Etc.nprocessors on every engine. Remember each
+    # worker is a full interpreter/VM process: on JVM engines that is a whole
+    # JVM with its own heap, so bound the pool (TURBO_TESTS2_MAX_PROCESSES)
+    # and the per-worker heap (e.g. JRUBY_OPTS) on memory-constrained
+    # runners — see README "Resource-Constrained CI (JVM Engines)".
     def start_subprocess(env, extra_args, tests, process_id, record_runtime:)
       if tests.empty?
         @messages << {
@@ -756,6 +764,14 @@ module TurboTests
     # on the queue forever — CI jobs hung for hours with no diagnostics.
     # On a stall we kill the surviving worker pids, report which groups
     # never finished, and fail the run instead.
+    #
+    # Note the OOM killer is the most common silent worker death on CI: the
+    # kernel kills the process with no stderr, no exit message, and no
+    # partial output. Workers are spawn-based real processes (never forked),
+    # so on JVM engines (JRuby, TruffleRuby) each one is a full JVM whose
+    # default heap can be 1/4 of machine RAM — a core-count pool of those
+    # exhausts a CI runner. Bound `workers x per-worker memory` on
+    # constrained runners (see README "Resource-Constrained CI").
     def pop_message_with_watchdog
       # 0 (the default) disables the watchdog: block indefinitely, exactly the
       # pre-watchdog behavior.
@@ -856,7 +872,10 @@ module TurboTests
               "outer process watcher (a CI job timeout, a container orchestrator, or a local supervisor) will then " \
               "be what eventually ends the run, usually without a useful stall report. A single long test only " \
               "trips this in serial lanes (TURBO_TESTS2_MAX_PROCESSES=1); in parallel lanes other workers keep " \
-              "messages flowing."
+              "messages flowing. Total silence in a PARALLEL lane usually means workers died rather than slowed " \
+              "down — the most common cause is the kernel OOM killer (each worker is a real spawned process; on " \
+              "JVM engines each is a full JVM whose default heap is 1/4 of RAM). Cap workers x per-worker memory: " \
+              "TURBO_TESTS2_MAX_PROCESSES=2 with a capped heap (e.g. JRUBY_OPTS=\"-J-Xmx1280m\")."
             )
             warned_silence = true
           end

data/lib/turbo_tests/version.rb

@@ -4,7 +4,7 @@ module TurboTests
   # Version namespace for this gem.
   module Version
     # Current gem version.
-    VERSION = "3.2.16"
+    VERSION = "3.2.17"
   end
   # Current gem version exposed at the traditional constant location.
   VERSION = Version::VERSION # Traditional Constant Location

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo_tests2
 version: !ruby/object:Gem::Version
-  version: 3.2.16
+  version: 3.2.17
 platform: ruby
 authors:
 - Illia
@@ -316,10 +316,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://turbo-tests2.galtzo.com
-  source_code_uri: https://github.com/galtzo-floss/turbo_tests2/tree/v3.2.16
-  changelog_uri: https://github.com/galtzo-floss/turbo_tests2/blob/v3.2.16/CHANGELOG.md
+  source_code_uri: https://github.com/galtzo-floss/turbo_tests2/tree/v3.2.17
+  changelog_uri: https://github.com/galtzo-floss/turbo_tests2/blob/v3.2.17/CHANGELOG.md
   bug_tracker_uri: https://github.com/galtzo-floss/turbo_tests2/issues
-  documentation_uri: https://www.rubydoc.info/gems/turbo_tests2/3.2.16
+  documentation_uri: https://www.rubydoc.info/gems/turbo_tests2/3.2.17
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/galtzo-floss/turbo_tests2/wiki
   news_uri: https://www.railsbling.com/tags/turbo_tests2